GreenPolyProducts/cantera
5
0
Fork 0
mirror of https://github.com/Cantera/cantera.git synced 2025-02-25 18:55:29 -06:00
Code Issues Packages Projects Releases Wiki Activity

merged with main

Browse Source
This commit is contained in:
jeremy karpowski 2025-02-03 09:29:24 +01:00
commit 94cf35e3a4
329 changed files with 10750 additions and 7377 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
.github/SUPPORT.md vendored
View File

@ -9,11 +9,6 @@ For **help**, **support** and **questions** please create a post on the
Any discussion of Cantera functionality such as how to use certain function
calls, syntax problems, input files, etc. should be directed to the Users' Group.
Further, the **[Cantera Gitter Chat](https://gitter.im/Cantera/Lobby)** is an
infrequently monitored chat room that can be used to discuss tangentially-related
topics such as how to model the underlying physics of a problem, share cool
applications that you have developed, etc.
Please **_do not_** raise an issue on GitHub unless it is a bug report or a
feature request. Issues that do not fall into these categories will be closed.
If you're not sure, please make a post on the
@ -22,16 +17,14 @@ be able to help you out.
## Documentation
The [documentation](https://cantera.org/documentation)
The [Cantera Website](https://cantera.org)
offers a number of starting points:
- [Python tutorial](https://cantera.org/tutorials/python-tutorial.html)
- [Application Examples in Python (Jupyter)](https://github.com/Cantera/cantera-jupyter#cantera-jupyter)
- [A guide to Cantera's input file format](https://cantera.org/tutorials/input-files.html)
- [Python tutorial](https://cantera.org/stable/userguide/python-tutorial.html)
- [Gallery of Python Examples](https://cantera.org/stable/examples/python/index.html)
- [A guide to Cantera's input file format](https://cantera.org/stable/userguide/input-tutorial.html)
- [Information about the Cantera community](https://cantera.org/community.html)
Documentation for the [development version of
Cantera](https://cantera.org/documentation/dev-docs.html) is also available.
- [Developers: Compile and Modify Cantera](https://cantera.org/stable/develop/index.html)
## Contributions

248
.github/workflows/main.yml vendored
View File

@ -5,14 +5,16 @@ on:
# Build on tags that look like releases
tags:
- v*
# Build when main or testing is pushed to
# Build when main, testing, or the maintenance branch is pushed to
branches:
- main
- testing
- "3.1"
pull_request:
# Build when a pull request targets main
# Build when a pull request targets main or the maintenance branch
branches:
- main
- "3.1"
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
@ -39,14 +41,14 @@ jobs:
- name: Install Apt dependencies
run: |
sudo apt update
sudo apt install libboost-dev gfortran libopenmpi-dev libblas-dev \
liblapack-dev libhdf5-dev
sudo apt install libboost-dev gfortran libopenmpi-dev libopenblas-openmp-dev \
libhdf5-dev
gcc --version
- name: Upgrade pip
run: python3 -m pip install -U pip setuptools wheel
- name: Install Python dependencies
run: |
python3 -m pip install ruamel.yaml scons==3.1.2
python3 -m pip install ruamel.yaml scons==4.0.1 packaging
- name: Build Cantera
run: |
python3 `which scons` build env_vars=all -j4 debug=n --debug=time \
@ -64,23 +66,25 @@ jobs:
timeout-minutes: 60
strategy:
matrix:
python-version: ['3.8', '3.10', '3.11', '3.12']
os: ['ubuntu-20.04', 'ubuntu-22.04']
python-version: ['3.10', '3.11', '3.12', '3.13']
os: ['ubuntu-24.04']
numpy: ['']
cython: ['']
include:
# Keep some test cases with NumPy 1.x until we drop support
- python-version: '3.12'
os: 'ubuntu-24.04'
os: 'ubuntu-22.04'
numpy: "'<2.0'"
# Keep some test cases with older Cython versions
- python-version: '3.10'
os: 'ubuntu-24.04'
os: 'ubuntu-22.04'
cython: "==0.29.31" # minimum supported version
- python-version: '3.11'
os: 'ubuntu-24.04'
os: 'ubuntu-22.04'
cython: "==3.0.8" # System version for Ubuntu 24.04
- python-version: '3.13'
os: 'ubuntu-22.04'
numpy: "'<2.2'"
fail-fast: false
steps:
- uses: actions/checkout@v4
@ -95,14 +99,14 @@ jobs:
- name: Install Apt dependencies
run: |
sudo apt update
sudo apt install libboost-dev gfortran libopenmpi-dev libblas-dev \
liblapack-dev libhdf5-dev libfmt-dev
sudo apt install libboost-dev gfortran libopenmpi-dev libopenblas-openmp-dev \
libhdf5-dev libfmt-dev
gcc --version
- name: Upgrade pip
run: python3 -m pip install -U pip setuptools wheel
- name: Install Python dependencies
run: |
python3 -m pip install ruamel.yaml scons==3.1.2 numpy${{ matrix.numpy }} \
python3 -m pip install ruamel.yaml scons==4.0.1 numpy${{ matrix.numpy }} \
cython${{ matrix.cython }} pandas pytest \
pytest-github-actions-annotate-failures pytest-xdist pint graphviz
- name: Build Cantera
@ -136,7 +140,7 @@ jobs:
if-no-files-found: error
clang-compiler:
name: LLVM/Clang with Python 3.8
name: LLVM/Clang with Python 3.13
runs-on: ubuntu-22.04
timeout-minutes: 60
steps:
@ -147,16 +151,17 @@ jobs:
- name: Setup Python
uses: actions/setup-python@v5
with:
python-version: 3.8
python-version: '3.13'
architecture: x64
- name: Install Apt dependencies
run: |
sudo apt update
sudo apt install libboost-dev gfortran libomp-dev libomp5 libopenblas-dev libhdf5-dev
sudo apt install libboost-dev gfortran libomp-dev libomp5 \
libopenblas-openmp-dev libhdf5-dev doxygen graphviz
- name: Upgrade pip
run: python3 -m pip install -U pip setuptools wheel
- name: Install Python dependencies
run: python3 -m pip install ruamel.yaml scons numpy cython pandas pytest
run: python3 -m pip install ruamel.yaml scons numpy cython pandas pytest Jinja2
pytest-xdist pytest-github-actions-annotate-failures pint graphviz
- name: Build Cantera
run: python3 `which scons` build env_vars=all
@ -172,6 +177,13 @@ jobs:
run: |
LD_LIBRARY_PATH=build/lib
python3 -m pytest -raP -v -n auto --durations=50 test/python
- name: Generate clib_experimental
run: |
python3 `which scons` doxygen
python3 interfaces/sourcegen/run.py --api=clib --output=.
python3 `which scons` build clib_experimental=y
- name: Run googletests for clib_experimental
run: python3 `which scons` test-clib-experimental --debug=time
macos-multiple-pythons:
name: ${{ matrix.macos-version }} with Python ${{ matrix.python-version }}
@ -179,14 +191,16 @@ jobs:
timeout-minutes: 90
strategy:
matrix:
macos-version: ['macos-12', 'macos-14']
python-version: ['3.11', '3.12']
macos-version: ['macos-13', 'macos-14', 'macos-15']
python-version: ['3.12', '3.13']
include:
- macos-version: 'macos-12'
python-version: '3.8'
- macos-version: 'macos-13'
python-version: '3.11'
- macos-version: 'macos-14'
python-version: '3.10'
extra-build-args: cxx_flags='-std=c++20'
- macos-version: 'macos-15'
python-version: '3.11'
fail-fast: false
steps:
- uses: actions/checkout@v4
@ -218,7 +232,7 @@ jobs:
# Pin to 4.3.4 to resolve errors around only uploading symlinks.
# See https://github.com/actions/upload-artifact/issues/589
uses: actions/upload-artifact@v4.3.4
if: matrix.python-version == '3.11' && matrix.macos-version == 'macos-12'
if: matrix.python-version == '3.12' && matrix.macos-version == 'macos-13'
with:
path: build/lib/libcantera_shared.dylib
name: libcantera_shared.dylib
@ -253,7 +267,8 @@ jobs:
- name: Install Apt dependencies
run: |
sudo apt update
sudo apt install libboost-dev gfortran liblapack-dev libblas-dev libsundials-dev libhdf5-dev
sudo apt install libboost-dev gfortran libopenblas-openmp-dev libsundials-dev \
libhdf5-dev
gcc --version
- name: Upgrade pip
run: python3 -m pip install -U pip setuptools wheel
@ -265,7 +280,7 @@ jobs:
- name: Setup .NET Core SDK
uses: actions/setup-dotnet@v4
with:
dotnet-version: '6.x'
dotnet-version: '8.x'
- name: Build Cantera
run: |
python3 `which scons` build blas_lapack_libs=lapack,blas coverage=y \
@ -314,10 +329,9 @@ jobs:
path: interfaces/dotnet/coveragereport*
retention-days: 5
- name: Upload Coverage to Codecov
uses: codecov/codecov-action@v4
uses: codecov/codecov-action@v5
with:
verbose: true
token: ${{secrets.CODECOV_TOKEN}}
files: ./coverage.xml,./build/pycov.xml,./interfaces/dotnet/coverage.cobertura.xml
fail_ci_if_error: true
@ -328,8 +342,6 @@ jobs:
defaults:
run:
shell: bash -l {0}
env:
DEPLOY: ${{ github.event_name == 'push' && github.repository_owner == 'Cantera' && endsWith(github.ref, 'main') }}
steps:
- uses: actions/checkout@v4
name: Checkout the repository
@ -346,7 +358,7 @@ jobs:
run: |
sudo apt update
sudo apt install libboost-dev graphviz texlive-bibtex-extra \
libblas-dev liblapack-dev libhdf5-dev libfmt-dev libsundials-dev
libopenblas-openmp-dev libhdf5-dev libfmt-dev libsundials-dev
- name: Upgrade pip
run: pip install -U pip setuptools wheel
- name: Install Python dependencies
@ -378,28 +390,72 @@ jobs:
cd build/doc
tar --exclude="*.map" --exclude="*.md5" -czf docs.tar.gz html
if: failure() || success()
- name: Store archive of docs output
- name: Store a copy of docs output
uses: actions/upload-artifact@v4
with:
path: build/doc/docs.tar.gz
name: docs
retention-days: 14
if: failure() || success()
- name: Determine whether to deploy
id: deploy-conf
if: ${{ github.event_name == 'push' && github.repository_owner == 'Cantera' }}
run: |
if [[ ${{ github.ref }} =~ ^refs\/heads\/([0-9]+\.[0-9]+)$ ]]; then
echo "match=true" >> $GITHUB_OUTPUT
echo "rsync_dest=cantera/${BASH_REMATCH[1]}" >> $GITHUB_OUTPUT
echo "commit=true" >> $GITHUB_OUTPUT
echo "git_dest=${BASH_REMATCH[1]}" >> $GITHUB_OUTPUT
echo "git_branch=staging" >> $GITHUB_OUTPUT
elif [[ ${{ github.ref }} == "refs/heads/main" ]]; then
echo "match=true" >> $GITHUB_OUTPUT
echo "rsync_dest=cantera/dev" >> $GITHUB_OUTPUT
elif [[ ${{ github.ref }} == "refs/heads/testing" ]]; then
echo "match=true" >> $GITHUB_OUTPUT
echo "rsync_dest=testing.cantera.org/dev" >> $GITHUB_OUTPUT
echo "commit=true" >> $GITHUB_OUTPUT
echo "git_dest=testing" >> $GITHUB_OUTPUT
echo "git_branch=testing" >> $GITHUB_OUTPUT
fi
# The known_hosts key is generated with `ssh-keygen -F cantera.org` from a
# machine that has previously logged in to cantera.org and trusts
# that it logged in to the right machine
- name: Set up SSH key and host for deploy
if: env.DEPLOY == 'true'
if: steps.deploy-conf.outputs.match == 'true'
uses: shimataro/ssh-key-action@v2
with:
key: ${{ secrets.CTDEPLOY_KEY }}
known_hosts: ${{ secrets.CTDEPLOY_HOST }}
- name: Upload the docs
if: env.DEPLOY == 'true'
- name: Commit docs to api-docs repo
if: steps.deploy-conf.outputs.commit == 'true'
env:
CANTERABOT_DOCS_TOKEN: ${{ secrets.CANTERABOT_DOCS_TOKEN }}
# Directory in api-docs repo: either the version (X.Y) or "testing"
GIT_DEST: ${{ steps.deploy-conf.outputs.git_dest }}
# Branch in api-docs to commit to: either 'staging' or 'testing'
BRANCH: ${{ steps.deploy-conf.outputs.git_branch }}
run: |
set -ex
REPO_SHA=`git rev-parse --short=8 HEAD`
git clone https://canterabot:${CANTERABOT_DOCS_TOKEN}@github.com/Cantera/api-docs
cd api-docs
git config user.name "CanteraBot"
git config user.email "96191898+CanteraBot@users.noreply.github.com"
git checkout --track origin/${BRANCH}
mkdir -p ${GIT_DEST}
tar -zxf ../build/doc/docs.tar.gz --strip-components=1 -C ${GIT_DEST}
git add .
git commit -m "Update for Cantera ${GIT_DEST} - Cantera/cantera@${REPO_SHA}"
git show --stat HEAD
git push origin
- name: Upload the docs to cantera.org
if: steps.deploy-conf.outputs.match == 'true'
env:
RSYNC_USER: "ctdeploy"
RSYNC_SERVER: "cantera.org"
RSYNC_DEST: "cantera/dev"
RSYNC_DEST: ${{ steps.deploy-conf.outputs.rsync_dest }}
DOCS_OUTPUT_DIR: "./build/doc/html/"
run: |
rsync -avzP --checksum --exclude='*.map' --exclude='*.md5' \
@ -415,30 +471,34 @@ jobs:
matrix:
# Keep some test cases with NumPy 1.x until we explicitly drop support
include:
- os: "ubuntu-20.04"
python-version: "3.8"
numpy: ""
- os: "ubuntu-22.04"
python-version: "3.8"
python-version: "3.10"
numpy: ""
- os: "ubuntu-20.04"
libhdf5: "libhdf5-103"
- os: "ubuntu-24.04"
python-version: "3.10"
numpy: "==1.21.6"
- os: "ubuntu-22.04"
python-version: "3.10"
numpy: ""
libhdf5: "libhdf5-103-1t64"
- os: "ubuntu-22.04"
python-version: "3.11"
numpy: "==1.23.5"
- os: "ubuntu-20.04"
libhdf5: "libhdf5-103"
- os: "ubuntu-24.04"
python-version: "3.11"
numpy: ""
libhdf5: "libhdf5-103-1t64"
- os: "ubuntu-22.04"
python-version: "3.12"
numpy: "==1.26.4"
- os: "ubuntu-20.04"
libhdf5: "libhdf5-103"
- os: "ubuntu-24.04"
python-version: "3.12"
numpy: ""
libhdf5: "libhdf5-103-1t64"
- os: "ubuntu-22.04"
python-version: "3.13"
numpy: ""
libhdf5: "libhdf5-103"
fail-fast: false
steps:
# We're not building Cantera here, we only need the checkout for the samples
@ -453,7 +513,7 @@ jobs:
- name: Install Apt dependencies
run: |
sudo apt update
sudo apt install graphviz libhdf5-103 libfmt-dev
sudo apt install graphviz ${{ matrix.libhdf5 }} libfmt-dev libopenblas0-openmp
- name: Download the wheel artifact
uses: actions/download-artifact@v4
with:
@ -475,10 +535,11 @@ jobs:
# See https://unix.stackexchange.com/a/392973 for an explanation of the -exec part.
# Skip 1D_packed_bed.py due to difficulty installing scikits.odes.
# Increase figure limit to handle flame_speed_convergence_analysis.py.
# Skip equations_of_state.py in cases where CoolProp is broken (temporarily, for Python 3.13)
run: |
ln -s libcantera_shared.so build/lib/libcantera_shared.so.3
rm samples/python/reactors/1D_packed_bed.py
rm samples/python/reactors/continuous_reactor.py
python3 -m CoolProp || rm samples/python/thermo/equations_of_state.py
echo "figure.max_open_warning: 100" > matplotlibrc
export LD_LIBRARY_PATH=build/lib
find samples/python -type f -iname "*.py" \
@ -505,24 +566,20 @@ jobs:
runs-on: ubuntu-latest
timeout-minutes: 60
env:
PYTHON_VERSION: 3.8
PYTHON_VERSION: '3.13'
defaults:
run:
shell: bash -l {0}
strategy:
matrix:
include:
- sundials-ver: 3
fmt-ver: 6.1.2
- sundials-ver: 4
fmt-ver: 8.1
- sundials-ver: 5.8
fmt-ver: 9.1
- sundials-ver: 6.4.1
fmt-ver: 10
- sundials-ver: 6.6
fmt-ver: 10
- sundials-ver: 7.0
- sundials-ver: 7.2
fmt-ver: 11
extra-build-args: cxx_flags='-std=c++20'
fail-fast: false
@ -577,21 +634,18 @@ jobs:
name: Windows 2022, Python ${{ matrix.python-version }}, fmt ${{ matrix.fmt-ver }}
runs-on: windows-2022
timeout-minutes: 60
defaults:
run:
shell: bash -l {0}
strategy:
matrix:
include:
- python-version: '3.8'
- python-version: '3.13'
fmt-ver: '10'
- python-version: '3.10'
fmt-ver: '8.1'
- python-version: '3.11'
fmt-ver: '9.1'
- python-version: '3.12'
fmt-ver: '7.1'
- python-version: '3.12'
fmt-ver: '10.0'
- python-version: '3.13'
fmt-ver: '11.0'
extra-build-args: cxx_flags='/EHsc /std:c++20 /utf-8'
fail-fast: false
@ -611,13 +665,12 @@ jobs:
python=${{ matrix.python-version }} scons numpy cython ruamel.yaml boost-cpp
eigen yaml-cpp pandas pytest pytest-xdist highfive pint python-graphviz
fmt=${{ matrix.fmt-ver }} setuptools
init-shell: powershell bash
post-cleanup: none
init-shell: powershell
- name: Build Cantera
run: scons build system_eigen=y system_yamlcpp=y system_highfive=y logging=debug
toolchain=msvc f90_interface=n debug=n ${{ matrix.extra-build-args }}
--debug=time -j4
shell: pwsh
- name: Upload shared library
# Pin to 4.3.4 to resolve errors around only uploading symlinks.
# See https://github.com/actions/upload-artifact/issues/589
@ -634,30 +687,30 @@ jobs:
- name: Run Python tests
run: |
pytest -raP -v -n auto --durations=50 test/python
shell: pwsh
- name: Test Install
# spot-check installation locations
run: |
set -x
scons install
test -f ${CONDA_PREFIX}/Library/bin/cantera_shared.dll
test -f ${CONDA_PREFIX}/Library/include/cantera/base/Solution.h
test -f ${CONDA_PREFIX}/Scripts/ck2yaml
test -f ${CONDA_PREFIX}/share/cantera/data/gri30.yaml
test -d ${CONDA_PREFIX}/share/cantera/samples
test -d ${CONDA_PREFIX}/share/cantera/samples/python
test -d ${CONDA_PREFIX}/Lib/site-packages/cantera
$paths = @('Library/bin/cantera_shared.dll',
'Library/include/cantera/base/Solution.h', 'Scripts/ck2yaml.exe',
'share/cantera/data/gri30.yaml', 'share/cantera/samples',
'share/cantera/samples/python', 'Lib/site-packages/cantera')
Foreach ($path in $paths) {
if (-not (Test-Path $Env:CONDA_PREFIX/$path)) {
echo "$path not found in install directory"
exit 1
}
}
- name: Test Essentials
# ensure that Python package loads and converter scripts work
run: |
set -x
python -c 'import cantera as ct; import sys; sys.exit(0) if ct.__version__.startswith("3.1.0") else sys.exit(1)'
ck2yaml --input=test/data/h2o2.inp --output=h2o2-test.yaml
test -f h2o2-test.yaml
if (-not (Test-Path h2o2-test.yaml)) { exit 1 }
cti2yaml test/data/ch4_ion.cti ch4_ion-test.yaml
test -f ch4_ion-test.yaml
if (-not (Test-Path ch4_ion-test.yaml)) { exit 1 }
yaml2ck data/h2o2.yaml --mechanism=h2o2-test.ck
test -f h2o2-test.ck
if (-not (Test-Path h2o2-test.ck)) { exit 1 }
windows:
name: "Windows 2019, MSVC ${{ matrix.vs-toolset }}, Python ${{ matrix.python-version }}"
@ -665,11 +718,11 @@ jobs:
timeout-minutes: 60
env:
BOOST_ROOT: ${{github.workspace}}/3rdparty/boost
BOOST_URL: https://boostorg.jfrog.io/artifactory/main/release/1.78.0/source/boost_1_78_0.7z
BOOST_URL: https://github.com/boostorg/boost/releases/download/boost-1.87.0/boost-1.87.0-b2-nodocs.7z
strategy:
matrix:
vs-toolset: ['14.2']
python-version: ["3.8", "3.10", "3.11", "3.12"]
python-version: ["3.10", "3.11", "3.12", "3.13"]
fail-fast: false
steps:
- uses: actions/checkout@v4
@ -690,23 +743,22 @@ jobs:
id: cache-boost
with:
path: ${{env.BOOST_ROOT}}
key: boost-178-win
key: boost-187-win
- name: Install Boost Headers
if: steps.cache-boost.outputs.cache-hit != 'true'
run: |
BOOST_ROOT=$(echo $BOOST_ROOT | sed 's/\\/\//g')
mkdir -p $BOOST_ROOT
curl --progress-bar --location --output $BOOST_ROOT/download.7z $BOOST_URL
7z -o$BOOST_ROOT x $BOOST_ROOT/download.7z -y -bd boost_1_78_0/boost
mv $BOOST_ROOT/boost_1_78_0/boost $BOOST_ROOT/boost
curl --progress-bar --location --output $BOOST_ROOT/download.7z -L $BOOST_URL
7z -o$BOOST_ROOT x $BOOST_ROOT/download.7z -y -bd boost-1.87.0/boost
mv $BOOST_ROOT/boost-1.87.0/boost $BOOST_ROOT/boost
rm $BOOST_ROOT/download.7z
shell: bash
- name: Build Cantera
run: scons build -j4 boost_inc_dir=%BOOST_ROOT% debug=n logging=debug
run: scons build -j4 boost_inc_dir=$Env:BOOST_ROOT debug=n logging=debug
python_package=y env_vars=USERPROFILE,GITHUB_ACTIONS
msvc_version=${{ matrix.vs-toolset }} f90_interface=n --debug=time
shell: cmd
- name: Build Tests
run: scons -j4 build-tests --debug=time
- name: Run compiled tests
@ -716,7 +768,7 @@ jobs:
# Adapted from https://www.scivision.dev/intel-oneapi-github-actions/
linux-intel-oneapi:
name: intel-oneAPI on Ubuntu, Python 3.8
name: intel-oneAPI on Ubuntu, Python 3.12
runs-on: ubuntu-latest
timeout-minutes: 60
env:
@ -743,7 +795,7 @@ jobs:
- name: Setup Python
uses: actions/setup-python@v5
with:
python-version: 3.8
python-version: '3.12'
architecture: x64
- name: Upgrade pip
run: python3 -m pip install -U pip setuptools wheel
@ -773,7 +825,7 @@ jobs:
timeout-minutes: 120 # MinGW is slooooow
env:
BOOST_ROOT: ${{github.workspace}}/3rdparty/boost
BOOST_URL: https://boostorg.jfrog.io/artifactory/main/release/1.78.0/source/boost_1_78_0.7z
BOOST_URL: https://github.com/boostorg/boost/releases/download/boost-1.87.0/boost-1.87.0-b2-nodocs.7z
steps:
- uses: actions/checkout@v4
name: Checkout the repository
@ -793,7 +845,7 @@ jobs:
id: cache-boost
with:
path: ${{env.BOOST_ROOT}}
key: boost-178-win
key: boost-187-win
- name: Set up MinGW
uses: egor-tensin/setup-mingw@v2
with:
@ -805,16 +857,15 @@ jobs:
run: |
BOOST_ROOT=$(echo $BOOST_ROOT | sed 's/\\/\//g')
mkdir -p $BOOST_ROOT
curl --progress-bar --location --output $BOOST_ROOT/download.7z $BOOST_URL
7z -o$BOOST_ROOT x $BOOST_ROOT/download.7z -y -bd boost_1_78_0/boost
mv $BOOST_ROOT/boost_1_78_0/boost $BOOST_ROOT/boost
curl --progress-bar --location --output $BOOST_ROOT/download.7z -L $BOOST_URL
7z -o$BOOST_ROOT x $BOOST_ROOT/download.7z -y -bd boost-1.87.0/boost
mv $BOOST_ROOT/boost-1.87.0/boost $BOOST_ROOT/boost
rm $BOOST_ROOT/download.7z
shell: bash
- name: Build Cantera
run: scons build -j4 boost_inc_dir=%BOOST_ROOT% debug=n logging=debug
run: scons build -j4 boost_inc_dir=$Env:BOOST_ROOT debug=n logging=debug
python_package=y env_vars=USERPROFILE,PYTHONPATH,GITHUB_ACTIONS
toolchain=mingw f90_interface=n --debug=time
shell: cmd
- name: Upload Wheel
uses: actions/upload-artifact@v4
with:
@ -849,9 +900,16 @@ jobs:
steps:
- uses: actions/checkout@v4
name: Checkout the repository
- name: Override default Python (Windows)
# Other operating systems use default system Python 3
uses: actions/setup-python@v5
with:
python-version: "3.10"
architecture: x64
if: matrix.os == 'windows-2022'
- name: Install Python dependencies
# Install for the default system Python 3, which is used by 'dotnet build'
run: python3 -m pip install ruamel.yaml Jinja2
# Install Python dependencies, which are used by 'dotnet build'
run: python3 -m pip install ruamel.yaml Jinja2 typing-extensions
- name: Install library dependencies with micromamba (Windows)
uses: mamba-org/setup-micromamba@v1
with:
@ -869,12 +927,12 @@ jobs:
- name: Install Apt dependencies (Ubuntu)
run: |
sudo apt update
sudo apt install libhdf5-dev libfmt-dev
sudo apt install libhdf5-dev libfmt-dev libopenblas0-openmp
if: matrix.os == 'ubuntu-22.04'
- name: Setup .NET Core SDK
uses: actions/setup-dotnet@v4
with:
dotnet-version: '6.x'
dotnet-version: '8.x'
- name: Download the Cantera shared library (.so)
uses: actions/download-artifact@v4
with:

12
.github/workflows/post-merge-tests.yml vendored
View File

@ -98,7 +98,7 @@ jobs:
pipenv install pytest-github-actions-annotate-failures
- name: Build Cantera
run: |
scons build env_vars=all -j4 debug=n --debug=time \
scons build env_vars=all -j4 debug=n --debug=time logging=debug \
system_eigen=y system_fmt=y system_sundials=y system_yamlcpp=y \
system_blas_lapack=y hdf_support=y f90_interface=y \
cc_flags=-D_GLIBCXX_ASSERTIONS python_package=y
@ -141,8 +141,8 @@ jobs:
highfive-devel python3-graphviz python3-packaging
- name: Build Cantera
run: |
scons build -j4 debug=n --debug=time python_package=y f90_interface=y \
extra_inc_dirs=/usr/include/eigen3 libdirname=/usr/lib64 \
scons build -j4 debug=n --debug=time logging=debug python_package=y \
f90_interface=y extra_inc_dirs=/usr/include/eigen3 libdirname=/usr/lib64 \
system_eigen=y system_fmt=y system_blas_lapack=y system_sundials=y \
system_yamlcpp=y system_blas_lapack=y hdf_support=y
# note: 'system_highfive=y' is omitted as the current packaged version is too old;
@ -192,7 +192,7 @@ jobs:
python3 -m pip install --pre numpy cython pandas scipy
- name: Build Cantera
run: |
python3 `which scons` build env_vars=all -j4 debug=n --debug=time \
python3 `which scons` build env_vars=all -j4 debug=n --debug=time logging=debug \
system_fmt=y system_blas_lapack=y hdf_support=y cc_flags=-D_GLIBCXX_ASSERTIONS \
python_package=y
- name: Build Tests
@ -233,7 +233,9 @@ jobs:
pytest-xdist pytest-github-actions-annotate-failures pint graphviz \
scons packaging
- name: Build Cantera
run: ./.venv/bin/scons build env_vars=all -j3 debug=n --debug=time boost_inc_dir=${BOOST_INC_DIR} python_package=y
run: |
./.venv/bin/scons build env_vars=all -j3 debug=n --debug=time logging=debug \
boost_inc_dir=${BOOST_INC_DIR} python_package=y
- name: Build Tests
run: ./.venv/bin/scons -j3 build-tests
- name: Run compiled tests

1
.gitignore vendored
View File

@ -40,6 +40,7 @@ environment.y*
*.mex*
*.asv
*.gv*
*.mod
.cproject
.project
.pydevproject

8
AUTHORS
View File

@ -10,6 +10,7 @@ Halla Ali (@hallaali)
Emil Atz (@EmilAtz)
Jongyoon Bae (@jongyoonbae), Brown University
Philip Berndt
Guus Bertens (@guusbertens), Eindhoven University of Technology
Wolfgang Bessler (@wbessler), Offenburg University of Applied Science
Paul Blum (@paulblum)
Tilman Bremer
@ -20,6 +21,8 @@ Ryan Crisanti
Nicholas Curtis (@arghdos)
Steven DeCaluwe (@decaluwe), Colorado School of Mines
Vishesh Devgan (@vdevgan)
Matthias Diener (@matthiasdiener), University of Illinois at Urbana-Champaign
Martey Dodoo (@martey)
Thomas Fiala (@thomasfiala), Technische Universität München
David Fronczek
Mark E. Fuller (@mefuller), Technion
@ -30,6 +33,8 @@ Dave Goodwin, California Institute of Technology
China Hagström (@chinahg), Massachusetts Institute of Technology
John Hewson (@jchewson), Sandia National Laboratory
Trevor Hickey (@luxe)
David Holland (@dholland88)
Zbigniew Jędrzejewski-Szmek (@keszybz), Red Hat
Yuanjie Jiang
Benjamin Kee (@lionkey)
Cory Kinney (@corykinney)
@ -51,6 +56,7 @@ Harry Moffat (@hkmoffat), Sandia National Laboratory
Christopher Neal (@wandadars)
Kyle Niemeyer (@kyleniemeyer), Oregon State University
Paul Northrop (@pwcnorthrop)
Chris Pilko (@cpilko)
Sebastian Pinnau (@spinnau)
Corey R. Randall (@c-randall), Colorado School of Mines
Andreas Rücker (@cannondale1492)
@ -59,11 +65,13 @@ Satyam Saxena (@CyberDrudge)
Ingmar Schoegl (@ischoegl), Louisiana State University
Santosh Shanbhogue (@santoshshanbhogue), Massachusetts Institute of Technology
Travis Sikes (@tsikes)
Patrick Singal (@pjsingal) Columbia University
Harsh Sinha (@sin-ha)
Sai Krishna Sirumalla (@skrsna), Northeastern University
David Sondak
Raymond Speth (@speth), Massachusetts Institute of Technology
Su Sun (@ssun30), Northeastern University
Daniel Thomas (@d-e-t), University of Minnesota
Sergey Torokhov (@band-a-prend)
Laurien Vandewalle (@lavdwall)
Guillaume Vignat (@gvignat), Stanford University

6
CITATION.cff
View File

@ -16,6 +16,6 @@ authors:
given-names: Bryan W.
orcid: https://orcid.org/0000-0003-0815-9270
title: "Cantera: An Object-oriented Software Toolkit for Chemical Kinetics, Thermodynamics, and Transport Processes"
version: "3.0.0"
doi: 10.5281/zenodo.8137090
date-released: 2023-08-22
version: "3.1.0"
doi: 10.5281/zenodo.14455267
date-released: 2024-12-14

5
INSTALL.md
View File

@ -15,4 +15,7 @@ shown by running `scons help`.
## Detailed Instructions
See the instructions available [online](https://cantera.org/install/compiling-install.html).
See the instructions available for installing packages providing the
[current stable version](https://cantera.org/stable/install/index.html) or compilation
instructions for building the
[latest development version](https://cantera.org/dev/develop/index.html).

35
README.rst
View File

@ -33,10 +33,10 @@ using the following MyBinder link:
Installation
============
|pip| |anaconda| |conda-forge|
|pip| |conda-forge|
`Installation instructions for the current release of Cantera
<https://cantera.org/install/index.html>`_ are available from the main `Cantera
<https://cantera.org/stable/install/index.html>`_ are available from the main `Cantera
documentation site <https://cantera.org>`_.
- The Python module can also be installed using pip on Windows, macOS, and Linux.
@ -48,28 +48,26 @@ documentation site <https://cantera.org>`_.
RHEL, Gentoo, and FreeBSD.
- For other platforms, or for users wishing to install a development version of
Cantera, `compilation instructions <https://cantera.org/install/compiling-install.html#sec-compiling>`_
Cantera, `compilation instructions <https://cantera.org/stable/develop/index.html>`_
are also available.
Documentation
=============
The `documentation <https://cantera.org/documentation>`_
offers a number of starting points:
The `documentation <https://cantera.org>`_ offers a number of starting points:
- `Python tutorial
<https://cantera.org/tutorials/python-tutorial.html>`_
<https://cantera.org/stable/userguide/python-tutorial.html>`_
- `Application Examples in Python
<https://cantera.org/examples/jupyter/index.html>`_
<https://cantera.org/stable/examples/python/index.html>`_
- `A guide to Cantera's input file format
<https://cantera.org/tutorials/input-files.html>`_
<https://cantera.org/stable/userguide/input-tutorial.html>`_
- `User Guide: Tutorials, FAQ, and Task Guides
<https://cantera.org/stable/userguide/index.html>`
- `Information about the Cantera community
<https://cantera.org/community.html>`_
- `Affiliated packages
<https://cantera.org/affiliated-packages.html>`_
`Documentation for the development version of Cantera
<https://cantera.org/documentation/dev-docs.html>`_ is also available.
<https://cantera.org/affiliated.html>`_
Code of Conduct
===============
@ -94,8 +92,8 @@ possible.
Development Site
================
The current development version is 3.1.0a4. The current stable version is
3.0.0. The `latest Cantera source code <https://github.com/Cantera/cantera>`_,
The current development version is 3.2.0a1. The current stable version is
3.1.0. The `latest Cantera source code <https://github.com/Cantera/cantera>`_,
the `issue tracker <https://github.com/Cantera/cantera/issues>`_ for bugs and
enhancement requests, `downloads of Cantera releases and binary installers
<https://github.com/Cantera/cantera/releases>`_ , and the `Cantera wiki
@ -125,7 +123,7 @@ development of Cantera through NumFOCUS.
:target: https://numfocus.org/donate-to-cantera
:alt: Powered by NumFOCUS
.. |cantera| image:: https://cantera.org/assets/img/cantera-logo.png
.. |cantera| image:: https://cantera.org/_static/cantera-logo.png
:target: https://cantera.org
:alt: cantera logo
:width: 675px
@ -134,8 +132,8 @@ development of Cantera through NumFOCUS.
.. |ci| image:: https://github.com/Cantera/cantera/workflows/CI/badge.svg
:target: https://github.com/Cantera/cantera/actions?query=workflow%3ACI+event%3Apush
.. |doi| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.8137090.svg
:target: https://doi.org/10.5281/zenodo.8137090
.. |doi| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.14455267.svg
:target: https://doi.org/10.5281/zenodo.14455267
.. |codecov| image:: https://img.shields.io/codecov/c/github/Cantera/cantera/main.svg
:target: https://codecov.io/gh/Cantera/cantera?branch=main
@ -147,8 +145,5 @@ development of Cantera through NumFOCUS.
.. |pip| image:: https://img.shields.io/pypi/v/cantera
:target: https://pypi.org/project/Cantera/
.. |anaconda| image:: https://img.shields.io/conda/v/cantera/cantera
:target: https://anaconda.org/Cantera/cantera
.. |conda-forge| image:: https://img.shields.io/conda/v/conda-forge/cantera
:target: https://anaconda.org/conda-forge/cantera

87
SConstruct
View File

@ -68,16 +68,6 @@ Additional command options:
# screen instead of doing <command>, for example
# 'scons build dump'. For debugging purposes.
# This f-string is deliberately here to trigger a SyntaxError when
# SConstruct is parsed by Python 2. This seems to be the most robust
# and simplest option that will reliably trigger an error in Python 2
# and provide actionable feedback for users.
f"""
Cantera must be built using Python 3.8 or higher. You can invoke SCons by executing
python3 `which scons`
followed by any desired options.
"""
from pathlib import Path
import sys
import os
@ -99,8 +89,8 @@ from buildutils import (Option, PathOption, BoolOption, EnumOption, Configuratio
config_error, run_preprocessor, make_relative_path_absolute)
# ensure that Python and SCons versions are sufficient for the build process
EnsurePythonVersion(3, 7)
EnsureSConsVersion(3, 0, 0)
EnsurePythonVersion(3, 10)
EnsureSConsVersion(4, 0, 0)
if not COMMAND_LINE_TARGETS:
# Print usage help
@ -144,6 +134,10 @@ if "clean" in COMMAND_LINE_TARGETS:
remove_file(name)
for name in Path("site_scons").glob("**/*.pyc"):
remove_file(name)
for name in Path("include/cantera/clib_experimental").glob("*.h"):
remove_file(name)
for name in Path("src/clib_experimental").glob("*.cpp"):
remove_file(name)
logger.status("Done removing output files.", print_level=False)
@ -163,7 +157,7 @@ logger.info(
f"SCons {SCons.__version__} is using the following Python interpreter:\n"
f" {sys.executable} (Python {python_version})", print_level=False)
cantera_version = "3.1.0a4"
cantera_version = "3.2.0a1"
# For use where pre-release tags are not permitted (MSI, sonames)
cantera_pure_version = re.match(r'(\d+\.\d+\.\d+)', cantera_version).group(0)
cantera_short_version = re.match(r'(\d+\.\d+)', cantera_version).group(0)
@ -180,9 +174,9 @@ else:
# Python Package Settings
python_min_version = parse_version("3.8")
python_min_version = parse_version("3.10")
# Newest Python version not supported/tested by Cantera
python_max_version = parse_version("3.13")
python_max_version = parse_version("3.14")
# The string is used to set python_requires in setup.cfg.in
py_requires_ver_str = f">={python_min_version},<{python_max_version}"
@ -324,14 +318,8 @@ config_options = [
interface further requires ruamel.yaml and pytest. The default
behavior is to build the full Python module for whichever version of
Python is running SCons if the required prerequisites (NumPy and
Cython) are installed. Note: 'y' is a synonym for 'full' and 'n' is a
synonym for 'none'.""",
# TODO: Remove 'minimal' after Cantera 3.1 is released. Leave it here for now
# to provide migration information.
# TODO: Remove 'none' and 'full' options after Cantera 3.1 is released. Prefer
# simpler 'y' and 'n' options, since we don't need to distinguish from the
# minimal interface.
"default", ("full", "none", "n", "y", "default", "minimal")),
Cython) are installed.""",
"default", ("n", "y", "default")),
PathOption(
"python_cmd",
"""Cantera needs to know where to find the Python interpreter. If
@ -380,6 +368,13 @@ config_options = [
"sphinx_docs",
"Build HTML documentation for Cantera using Sphinx.",
False),
BoolOption(
"clib_experimental",
"""Build experimental CLib. Requires running 'scons doxygen' and CLib code
generation via 'python3 interfaces/sourcegen/run.py --api=clib --output=.'
prior to 'scons build' command.
""",
False),
BoolOption(
"run_examples",
"""Run examples to generate plots and outputs for Sphinx Gallery. Disable to
@ -850,8 +845,6 @@ if os.name == "nt":
elif windows_compiler_env["toolchain"] == "mingw":
toolchain = ["mingw", "f90"]
extraEnvArgs["F77"] = None
# Next line fixes https://github.com/SCons/scons/issues/2683
extraEnvArgs["WINDOWS_INSERT_DEF"] = 1
elif windows_compiler_env["toolchain"] == "intel":
toolchain = ["intelc"] # note: untested
@ -955,16 +948,6 @@ opts.AddVariables(*config.to_scons())
opts.Update(env)
opts.Save('cantera.conf', env)
# TODO: Remove after Cantera 3.1, when the minimal option is removed from the
# configuration.
if env["python_package"] == "minimal":
logger.error(
"The 'minimal' option for the Python package was removed in Cantera 3.1. "
"Please build the full interface by passing 'python_package=y' or turn off the "
"interface with 'python_package=n'"
)
sys.exit(1)
# Expand ~/ and environment variables used in cantera.conf (variables used on
# the command line will be expanded by the shell)
for option in opts.keys():
@ -1255,7 +1238,7 @@ if env['system_fmt'] in ('y', 'default'):
)
if retcode and fmt_version_text:
fmt_lib_version = split_version(fmt_version_text)
fmt_min_version = "6.1.2"
fmt_min_version = "8.0.0"
if parse_version(fmt_lib_version) < parse_version(fmt_min_version):
if env['system_fmt'] == 'y':
config_error(
@ -1263,7 +1246,7 @@ if env['system_fmt'] in ('y', 'default'):
f"version {fmt_min_version} or higher is required.")
else:
env['system_fmt'] = True
logger.info(f"Using system installation of fmt library.")
logger.info("Using system installation of fmt library.")
elif env['system_fmt'] == 'y':
config_error('Expected system installation of fmt library, but it '
'could not be found.')
@ -1280,11 +1263,7 @@ if env['system_fmt'] in ('n', 'default'):
fmt_lib_version = split_version(fmt_version_text)
env['system_fmt'] = False
logger.info(f"Using private installation of fmt library.")
if env["OS"] == "Windows" and parse_version(fmt_lib_version) < parse_version("8.0.0"):
# Workaround for symbols not exported on Windows in older fmt versions
env.Append(CPPDEFINES={"FMT_HEADER_ONLY": 1})
logger.info("Using private installation of fmt library.")
logger.info(f"Using fmt version {fmt_lib_version}")
@ -1375,7 +1354,7 @@ env['HAS_OPENMP'] = conf.CheckLibWithHeader(
["iomp5", "omp", "gomp"], "omp.h", language="C++"
)
_, boost_lib_version = run_preprocessor(conf, ["<boost/version.hpp>"], "BOOST_LIB_VERSION")
retcode, boost_lib_version = run_preprocessor(conf, ["<boost/version.hpp>"], "BOOST_LIB_VERSION")
if not retcode:
config_error("Boost could not be found. Install Boost headers or set "
"'boost_inc_dir' to point to the boost headers.")
@ -1648,29 +1627,19 @@ debug_message = [
logger.debug("\n".join(debug_message), print_level=False)
env['python_cmd_esc'] = quoted(env['python_cmd'])
# TODO: Remove this check when 'full' and 'none' are removed
if env['python_package'] == 'full':
logger.warning("The 'full' specification is deprecated and should be replaced by 'y'")
env['python_package'] = 'y' # Allow 'full' as a synonym for 'y'
elif env['python_package'] == 'none':
logger.warning("The 'none' specification is deprecated and should be replaced by 'n'")
env['python_package'] = 'n' # Allow 'none' as a synonym for 'n'
env["python_min_version"] = python_min_version
env["python_max_version"] = python_max_version
env["py_requires_ver_str"] = py_requires_ver_str
env["cython_version_spec"] = SpecifierSet(">=0.29.31", prereleases=True)
env["numpy_version_spec"] = SpecifierSet(">=1.12.0,<3", prereleases=True)
# When updating NumPy spec, also update interfaces/python_sdist/pyproject.toml.in.
env["numpy_version_spec"] = SpecifierSet(">=1.21.0,<3", prereleases=True)
env["cython_version_spec_str"] = str(env["cython_version_spec"])
env["numpy_version_spec_str"] = str(env["numpy_version_spec"])
# We choose ruamel.yaml 0.15.34 as the minimum version
# since it is the highest version available in the Ubuntu
# 18.04 repositories and seems to work. Older versions such as
# 0.13.14 on CentOS7 and 0.10.23 on Ubuntu 16.04 raise an exception
# that they are missing the RoundTripRepresenter
env["ruamel_version_spec"] = SpecifierSet(">=0.15.34", prereleases=True)
# We choose ruamel.yaml 0.17.16 as the minimum version since it is the highest version
# available in the Ubuntu 22.04 repositories. When updating this, also update the
# version string in interfaces/python_sdist/pyproject.toml.in.
env["ruamel_version_spec"] = SpecifierSet(">=0.17.16", prereleases=True)
env["ruamel_version_spec_str"] = str(env["ruamel_version_spec"])
# Minimum pytest version assumed based on Ubuntu 20.04

5
doc/doxygen/Doxyfile
View File

@ -48,7 +48,7 @@ PROJECT_NAME = Cantera
# could be handy for archiving the generated documentation or if some version
# control system is used.
PROJECT_NUMBER = 3.1.0a4
PROJECT_NUMBER = 3.2.0a1
# Using the PROJECT_BRIEF tag one can provide an optional one line description
# for a project that appears at the top of each page and should give viewer a
@ -1013,7 +1013,8 @@ RECURSIVE = YES
# Note that relative paths are relative to the directory from which doxygen is
# run.
EXCLUDE = include/cantera/ext
EXCLUDE = include/cantera/ext \
include/cantera/clib_experimental
# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
# directories that are symbolic links (a Unix file system feature) are excluded

22
doc/doxygen/versions.md
View File

@ -2,16 +2,16 @@
> **Note:** For release notes and previous versions of the Python/MATLAB
> interface documentation, refer to
> [cantera.org](https://cantera.org/documentation/index.html#need-something-else).
> [cantera.org](https://cantera.org/stable/reference/index.html).
**%Cantera Developer API** versions:
**%Cantera C++ API** versions:
* [dev/latest](https://cantera.org/documentation/dev/doxygen/html/index.html) (unstable)
* [v3.0.0](https://cantera.org/documentation/docs-3.0/doxygen/html/index.html)
* [v2.6.0](https://cantera.org/documentation/docs-2.6/doxygen/html/modules.html)
* [v2.5.1](https://cantera.org/documentation/docs-2.5/doxygen/html/modules.html)
* [v2.4.0](https://cantera.org/documentation/docs-2.4/doxygen/html/modules.html)
* [v2.3.0](https://cantera.org/documentation/docs-2.3/doxygen/html/modules.html)
* [v2.2.1](https://cantera.org/documentation/docs-2.2/doxygen/html/modules.html)
* [v2.1.2](https://cantera.org/documentation/docs-2.1/doxygen/html/modules.html)
* [v2.0.2](https://cantera.org/documentation/docs-2.0/doxygen/html/modules.html)
* [dev/latest](https://cantera.org/dev/cxx/index.html) (unstable)
* [v3.0.0](https://cantera.org/3.0/doxygen/html/index.html)
* [v2.6.0](https://cantera.org/2.6/doxygen/html/modules.html)
* [v2.5.1](https://cantera.org/2.5/doxygen/html/modules.html)
* [v2.4.0](https://cantera.org/2.4/doxygen/html/modules.html)
* [v2.3.0](https://cantera.org/2.3/doxygen/html/modules.html)
* [v2.2.1](https://cantera.org/2.2/doxygen/html/modules.html)
* [v2.1.2](https://cantera.org/2.1/doxygen/html/modules.html)
* [v2.0.2](https://cantera.org/2.0/doxygen/html/modules.html)

27
doc/sphinx/_static/doc-versions.json
View File

@ -1,40 +1,45 @@
[
{
"name": "3.1 (dev)",
"version": "3.1",
"name": "3.2 (dev)",
"version": "3.2",
"url": "/dev/"
},
{
"name": "3.0.0 (stable)",
"name": "3.1.0 (stable)",
"version": "3.1",
"url": "/3.1/"
},
{
"name": "3.0.0",
"version": "3.0.0",
"url": "/documentation/docs-3.0/sphinx/html/"
"url": "/3.0/sphinx/html/"
},
{
"version": "2.6.0",
"url": "/documentation/docs-2.6/sphinx/html/"
"url": "/2.6/sphinx/html/"
},
{
"version": "2.5.1",
"url": "/documentation/docs-2.5/sphinx/html/"
"url": "/2.5/sphinx/html/"
},
{
"version": "2.4.0",
"url": "/documentation/docs-2.4/sphinx/html/"
"url": "/2.4/sphinx/html/"
},
{
"version": "2.3.0",
"url": "/documentation/docs-2.3/sphinx/html/"
"url": "/2.3/sphinx/html/"
},
{
"version": "2.2.1",
"url": "/documentation/docs-2.2/sphinx/html/"
"url": "/2.2/sphinx/html/"
},
{
"version": "2.1.2",
"url": "/documentation/docs-2.1/sphinx/html/"
"url": "/2.1/sphinx/html/"
},
{
"version": "2.0.2",
"url": "/documentation/docs-2.0/sphinx/html/"
"url": "/2.0/sphinx/html/"
}
]

1
doc/sphinx/ctutils.py
View File

@ -6,7 +6,6 @@ class ResetArgv:
wants_plot = {
"adiabatic.py",
"premixed_counterflow_twin_flame.py",
"piston.py",
"reactor1.py",
"reactor2.py",
"sensitivity1.py",

8
doc/sphinx/develop/compiling/compilation-reqs.md
View File

@ -113,7 +113,7 @@ compile Cantera on your operating system.
channels:
- conda-forge
dependencies:
- python # Cantera supports Python 3.8 and up
- python # Cantera supports Python 3.10 and up
- scons # build system
- boost-cpp # C++ dependency
- hdf5 # optional C++ dependency
@ -224,9 +224,9 @@ Next: Download the Source Code
### Ubuntu & Debian
- Ubuntu 20.04 LTS (Focal Fossa) or newer
- Ubuntu 22.04 LTS (Focal Fossa) or newer
- Debian 11.0 (Bullseye) or newer
- Debian 12.0 (Bookworm) or newer
- The following packages must be installed to build any of the Cantera modules using
your choice of package manager:
@ -424,7 +424,7 @@ Next: Download the Source Code
- Python
- <https://www.python.org/downloads/>
- Cantera supports Python 3.8 and higher
- Cantera supports Python 3.10 and higher
- Be sure to choose the appropriate architecture for your system - either
32-bit or 64-bit
- When installing, make sure to choose the option to add to your `PATH`

19
doc/sphinx/develop/compiling/dependencies.md
View File

@ -26,8 +26,8 @@ compiler is required only if you plan to build the Fortran module.
- Microsoft compilers (C/C++)
- Known to work with Visual Studio 2017 (MSVC 14.1), Visual Studio 2019 (MSVC 14.2)
and Visual Studio 2022 (MSVC 14.3).
- Known to work with Visual Studio 2019 (MSVC 14.2) and Visual Studio 2022
(MSVC 14.3).
- MinGW (C/C++/Fortran)
@ -40,14 +40,14 @@ compiler is required only if you plan to build the Fortran module.
- SCons:
- <http://scons.org/tag/releases.html>
- Works with versions >= 3.0.0
- Works with versions >= 4.0.0
- On Windows, more recent SCons versions are required to support each new version of
the MSVC compiler.
- Python:
- <https://python.org/downloads/>
- Works with versions >= 3.8.
- Works with versions >= 3.10.
- Boost
@ -63,7 +63,7 @@ compiler is required only if you plan to build the Fortran module.
Git, SUNDIALS will be automatically downloaded and the necessary portions will be
compiled and installed with Cantera.
- <https://computing.llnl.gov/projects/sundials>
- Known to work with versions >= 3.0 and \<= 7.0.
- Known to work with versions >= 5.0 and \<= 7.2.
- To use SUNDIALS with Cantera on a Linux/Unix system, it must be compiled
with the `-fPIC` flag. You can specify this flag when configuring SUNDIALS as
`cmake -DCMAKE_C_FLAGS=-fPIC <other command-line options>`
@ -81,7 +81,7 @@ compiler is required only if you plan to build the Fortran module.
Cantera source code using Git, fmt will be automatically downloaded and the
necessary portions will be compiled and installed with Cantera.
- <https://fmt.dev/latest/index.html>
- Known to work with versions 6.1.2 through 11.0.
- Known to work with versions 8.0 through 11.0.
- yaml-cpp
@ -97,7 +97,7 @@ compiler is required only if you plan to build the Fortran module.
- Required to build the Cantera Python module, and to run significant portions
of the test suite.
- Expected to work with versions >= 1.12.0. 1.16.0 or newer is recommended.
- Expected to work with versions >= 1.21.0.
- [Cython](https://cython.org/)
@ -121,8 +121,7 @@ compiler is required only if you plan to build the Fortran module.
- Required to convert input files from Chemkin, {term}`CTI`, and XML to the YAML
format
- Known to work with versions 0.15.42, 0.15.87, and 0.16.5
- Expected to work with versions >= 0.15.0
- Expected to work with versions >= 0.17.16
- [libhdf5](https://www.hdfgroup.org/solutions/hdf5/)
@ -213,4 +212,4 @@ compiler is required only if you plan to build the Fortran module.
- [.NET](https://dotnet.microsoft.com/)
- Required for the compilation of the experimental .NET interface
- Known to work for the .NET 6.0 SDK
- Known to work for the .NET 8.0 SDK

12
doc/sphinx/develop/compiling/source-code.md
View File

@ -13,7 +13,7 @@
Then, check out the tag of the most recent stable version:
```bash
git checkout tags/v3.0.0
git checkout tags/v3.1.0
git submodule update
```
@ -49,7 +49,7 @@ Next: Configure & Build Cantera
- **Option 1**: Check out the tag with the most recent beta release:
```bash
git checkout tags/v3.0.0b1
git checkout tags/v3.1.0b1
git submodule update
```
@ -64,17 +64,17 @@ Next: Configure & Build Cantera
release of the stable version:
```bash
git checkout 3.0
git checkout 3.1
git submodule update
```
This branch has all the work on the 3.0.x version of the software.
This branch has all the work on the 3.1.x version of the software.
If you've already checked out the 3.0 branch, you can get the latest updates from the
If you've already checked out the 3.1 branch, you can get the latest updates from the
main Cantera repository and synchronize your local repository by running:
```bash
git checkout 3.0
git checkout 3.1
git fetch --all
git pull --ff-only
```

31
doc/sphinx/develop/distribution-packages/conda.md
View File

@ -1,5 +1,32 @@
# Distributing Conda Package via conda-forge
🚧 This page is under construction 🚧
The Conda recipe hosted at <https://github.com/conda-forge/cantera-feedstock> is used
to build packages for both stable and pre-release versions of Cantera.
<https://github.com/conda-forge/cantera-feedstock>
## Stable Cantera releases
- fork the repository above
- Update `recipe/meta.yaml`:
- Change the header line that looks like `{% set version = "3.1.0" %}`
- In the `source` section, update the `url` and `sha256` for both the main `cantera`
repo as well as the `cantera-example-data` repo.
- The hash in the `url` is the hash of the commit corresponding to the tagged
release.
- The easiest way to get the `sha256` of the archive is to download it from that URL
and run `sha256sum` on that file.
- Update the value of `CT_GIT_COMMIT` with the same hash as used in the URL for the
`cantera` repository.
- Under `build`, reset the `number` to 0.
- Do whatever else is needed to bring the conda-forge recipe up to date, for example
by using conda-smithy.
- Create a pull request against the `main` branch of `conda-forge/cantera-feedstock`
- Once the PR is merged, you should be able to see the status of the final package
builds in [Azure DevOps](https://dev.azure.com/conda-forge/feedstock-builds/_build?definitionId=11466&_a=summary)
## Cantera pre-releases
- Follow the same steps as above but create the pull request against the `dev` branch of
`conda-forge/cantera-feedstock`
- Whether your starting point should be the existing `main` or `dev` branch is a bit
tricky. In either case, there are likely to be conflicts to work out. Use caution to
make sure that important updates to the build aren't lost when merging branches.

66
doc/sphinx/develop/distribution-packages/pypi-sdist-wheel.md
View File

@ -33,10 +33,12 @@ testing.
1. Install SCons and [build](https://pypi.org/project/build/)
1. Run `scons sdist`
a. `scons clean sdist` can also be used to automatically remove the
`build` folder prior to building the `sdist.
`build` folder prior to building the `sdist`.
1. Building the wheel requires that Boost and libhdf5 are available on the build system.
If these are not installed in standard locations, you can set `BOOST_ROOT` and
`HDF5_ROOT` environment variables to point to the correct location.
If these are not installed in standard locations, you can set the `Boost_ROOT` and
`HDF5_ROOT` environment variables to point to the correct location. On Linux, you
will also need to install OpenBLAS (macOS uses Apple's Accelerate framework to
provide LAPACK).
1. Change to the `build/python_sdist/dist` folder
1. Unpack the sdist: `tar xf cantera-3.1.0a2.tar.gz`. Note the version `3.1.0a2` may be
different.
@ -54,13 +56,16 @@ pip install <path to the wheel>`.
Sdists are built from the git checkout using SCons. Starting with v3.1, the only
dependencies required to build the sdist are SCons and
build. Dependencies such as NumPy, Boost, or any of
`build` (also known as `pyproject-build`). Dependencies such as NumPy, Boost, or any of
the dependencies available as submodules are not necessary to build the sdist.
To build the sdist, run `scons sdist` from the repository root.
```{note}
For versions 2.6 and 3.0, all the usual dependencies to build Cantera from source are required. Starting with 3.1, the build process for the sdist was simplified to pull in external dependencies at wheel-build time, rather than copying code from the Cantera external source tree into the sdist.
For versions 2.6 and 3.0, all the usual dependencies to build Cantera from source
are required. Starting with 3.1, the build process for the sdist was simplified to
pull in external dependencies at wheel-build time, rather than copying code from the
Cantera external source tree into the sdist.
```
The code for the sdist is located in the `interfaces/python_sdist` folder. Building the
@ -110,9 +115,12 @@ wheel. Most of the configuration for the wheel build is therefore done in the
the `build/python_sdist` folder and from there into the actual sdist tarball.
```{note}
The minimum required version of CMake is 3.24 to support all the options we use with
`FetchContent`. A compatible version should be installed by scikit-build-core if it
isn't available on the system.
The minimum required version of CMake is 3.27 to support all the options we use with
[`FetchContent`](https://cmake.org/cmake/help/latest/module/FetchContent.html). A
compatible version should be installed by `scikit-build-core` if it isn't available
on the system. Linux and macOS hosts also require the Ninja build system, version 1.11
or greater. This should also be installed by `scikit-build-core` at build time if isn't
available on the system.
```
There are essentially 4 stages to the wheel build:
@ -130,8 +138,8 @@ built during the wheel build and must be pre-installed on the build system. I co
find a way to have eigen and HighFive, respectively, find those dependencies if they
were also installed using `FetchContent`. If Boost and libhdf5 are installed in
non-standard directories, you can use the `Boost_ROOT` or `Boost_INCLUDE_DIRS` and
`HDF5_ROOT` variables to specific the correct locations. See the CMake documentation for
`find_package()`.
`HDF5_ROOT` variables to specify the correct locations. See the CMake documentation for
[`find_package()`](https://cmake.org/cmake/help/latest/command/find_package.html).
```
Steps 1 and 2 above are set up in the `interfaces/python_sdist/src/CMakeLists.txt` file.
@ -143,16 +151,40 @@ When a version of Cantera is ready to be published to PyPI, the workflow in the
[pypi-packages](https://github.com/Cantera/pypi-packages) repository must be executed.
The workflow essentially conducts the steps in the [](#tldr) section above.
The one big addition to the GitHub Action workflow is that there are a couple of shell
scripts in the `pypi-packages` repository to build libhdf5 for macOS and Windows. On
macOS, we also link to `libaec` so there's a small patch for the CMakeLists.txt file in
`libaec`.
The one big addition to the GitHub Actions workflow is that there are a couple of shell
scripts in the `pypi-packages` repository to build libhdf5, HighFive, and SUNDIALS for
macOS and Windows.
For Linux builds, we have a [custom-built manylinux
image](https://github.com/Cantera/hdf5-boost-manylinux) that already has the
dependencies installed. This saves time compiling libhdf5 on Linux/ARM builds because
those are emulated and already very slow.
image](https://github.com/Cantera/cantera-base-manylinux) that already has the
dependencies installed. This saves time compiling our dependencies on Linux/ARM builds
because those are emulated and already very slow.
As much of the configuration for `cibuildwheel` as possible is done statically in
`pyproject.toml.in`. Only values that are dynamically determined when the workflow runs
should be set in the workflow.
This workflow should be automatically triggered when a new version of Cantera is tagged,
identified by a tag matching the pattern `v*`. This is managed by the GitHub action
workflow in `.github/workflows/packaging.yml` in the main Cantera repository. You can
[check the status](https://github.com/Cantera/pypi-packages/actions/workflows/python-package.yml)
of these package builds or trigger the workflow manually (in case it fails and requires
updates after the tag is pushed).
After the workflow successfully builds the packages, it will prompt the Cantera
maintainers to approve deploying the release to PyPI. Before doing so, download and test
some of the wheels that are uploaded as "artifacts" on GitHub.
## Tips
* You can manually run the packaging build in the `pypi-packages` repository by going
to the _Actions_ tab in the repository and manually running the workflow. Choose
your branch from the dropdown and paste in a commit from the `Cantera/cantera`
repository. You can paste any valid commit associated with Cantera, including commits
from branches associated with pull requests in `Cantera/cantera`.
* With CMake 3.27 or later, `*_ROOT` locations for dependencies can be spelled as either
the canonical spelling defined by the library (for example, `Boost_ROOT`) or as all
upper-case (for example, `BOOST_ROOT`). This behavior is configured by [CMake Policy
0144](https://cmake.org/cmake/help/latest/policy/CMP0144.html).
[manylinux]:

117
doc/sphinx/develop/distribution-packages/release-checklist.md Normal file
View File

@ -0,0 +1,117 @@
# Making a New Cantera Release
Checklist for making a new Cantera release. This is mainly useful to Cantera
maintainers.
## Before the Release
- Reserve DOI on Zenodo.
- Check the [documentation](https://cantera.org/dev/) for accessibility concerns, for
example by using the
[Lighthouse](https://developer.chrome.com/docs/lighthouse/overview) tool built into
Chrome.
- Check both Sphinx-generated and Doxygen-generated pages.
- In addition to the automated checks done by Lighthouse, consider some of the manual
checks that it suggests, such as testing that pressing the "tab" key cycles through
page elements in a logical order.
- The most likely changes affecting accessibility would come from changes to the
versions of the tools used to build the documentation, particularly Doxygen, Sphinx,
and the Pydata Sphinx theme. For consistency, these all have pinned versions used
in the `docs` CI build defined in `.github/workflows/main.yml`.
- Check the versions of dependencies that we suggest work for installing/compiling
Cantera.
- Installation instructions in `doc/sphinx/install/*.md`
- `doc/sphinx/develop/compiling/dependencies.md`
- `doc/sphinx/develop/compiling/compilation-reqs.md`
## Release Pull Request
- Make sure version is set correctly:
- `SConstruct`: `'cantera_version'` (most widely used)
- `README.rst`
- `doc/doxygen/Doxyfile`: `'PROJECT_NUMBER'`
- `ck2yaml.py`, `cti2yaml.py`, and `ctml2yaml.py`
- For final (non alpha/beta) releases, make sure any alpha/beta suffixes are removed
from the `cantera-version` field of any YAML input files that have been updated
- Installation instructions (`doc/sphinx/install/*.md`)
- Update branch names given in compilation instructions
(`doc/sphinx/develop/compiling/source-code.md`)
- Update entries in `doc/sphinx/_static/doc-versions.json`
- Update DOI in `README.rst` and `CITATION.cff`
- Make sure copyright years are correct:
- `doc/sphinx/conf.py`
- `License.txt`
- Add release notes to `doc/sphinx/reference/releasenotes/vX.Y.md`, linked from
`doc/sphinx/reference/releasenotes/index.md`.
- The [`graphql.py`](https://github.com/Cantera/cantera-release-guide/blob/main/graphql.py)
and [`commiting-users.py`](https://github.com/Cantera/cantera-release-guide/blob/main/commiting-users.py)
scripts in the `cantera-release-guide` repo can help with generating some of this
content.
## After Merging Release Pull Request
- Update the recommended citation in `community.md` in the `cantera-website` repository,
including the year and DOI.
- Create a tag for the revision corresponding to the release. If this is a feature
release, also create a maintenance branch. Assuming `upstream` corresponds to the
`Cantera/cantera` repository:
```
git tag -a vX.Y.Z
# Tag message: "Cantera X.Y.Z release"
git push upstream vX.Y.Z
git checkout -b X.Y
git push upstream X.Y
```
- Also create a tag in the `cantera-example-data` repository for the commit that
corresponds to the tagged commit in the main repository. This is needed to build the
Ubuntu packages.
- The CI job on the maintenance branch should upload the docs to the versioned path on
`cantera.org` and archive the docs in the `staging` branch of the
[`api-docs`](https://github.com/Cantera/api-docs/tree/staging) repository. Check that
this worked correctly and merge into the `main` branch if so. Consider squashing
multiple updates to the same version to keep this repository from growing too much.
- If this is a feature release, log into `cantera.org` and update the symlink
`/var/www/cantera/stable` to point to the docs for the new feature branch.
- Create the release tarball. This requires a couple of steps to merge the
`example_data` submodule in with the main source directories:
```sh
# (after checking out the release commit)
git archive --format=tar --prefix=cantera/ HEAD >source.tar
cd data/example_data
git archive --format=tar --prefix=cantera/data/example_data/ HEAD >../../example-data.tar
cd ../..
bsdtar czvf cantera-X.Y.Z.tar.gz @source.tar @example-data.tar
rm source.tar example-data.tar
```
- The trailing slash on the `--prefix` argument is _really important_. Otherwise,
the files won't go into a folder.
- Inspect the contents of the archive to make sure the directory structure looks correct:
```
tar tvf cantera-X.Y.Z.tar.gz
```
- The `bsdtar` tool can be installed on Debian/Ubuntu from the `libarchive-tools`
package, or the `libarchive` Conda package. It is installed by default on macOS (and
is the same as `tar`).
- Build officially-maintained packages
- [PyPI](pypi-sdist-wheel)
- [conda-forge](conda)
- [Ubuntu](ubuntu-ppa)
- Generate the detailed Changelog using the
[`graphql.py`](https://github.com/Cantera/cantera-release-guide/blob/main/graphql.py)
script from the `cantera-release-guide` repo and put the resulting list in the
[wiki](https://github.com/Cantera/cantera/wiki)
- Update text and links in the "welcome" message of the
[Cantera Users' Group](https://groups.google.com/g/cantera-users).

13
doc/sphinx/develop/doc-formatting.md
View File

@ -51,12 +51,21 @@ This page provides some notes on useful syntax for writing in these various form
```
## Useful reST syntax
reStructuredText is used in the docstrings for the Python package and in the comment
blocks in the examples that are parsed by Sphinx Gallery.
- Linking to a Sphinx label:
- `` :ref:`sec-label-name` `` (automatic name)
- `` :ref:`link text <sec-label-name>` `` (specified link text)
- Linking to a Sphinx page:
- `` :doc:`/absolute/path` `` (automatic name)
- Caution on usage of single backticks versus double backticks -- the former are only for linking to things using the default role (that is, Python objects)
- Linking to examples:
- `` :doc:`example_name.py </examples/python/subdir/example_name>` ``
- Caution on usage of single backticks versus double backticks -- the former are only
for linking to things using the default role (that is, Python objects)
## Useful Doxygen syntax
- Linking to a Sphinx page: `[link text](../reference/science/phasethermo/lattice.html)`
- Linking to a Sphinx page: `[link text](../reference/thermo/species-thermo.html)`
- Citations: `@cite authorYYYY` will generate a numbered citation like `[8]`, assuming
`authorYYYY` is a key in `doc/doxygen/cantera.bib`.
- Equations can be added using LaTeX input bracketed by `@f[` and `@f]`.

6
doc/sphinx/develop/index.md
View File

@ -69,18 +69,20 @@ doc-formatting
```
(sec-distributing)=
## Distributing Built Cantera Packages
## Releasing & Distributing Cantera
- [](distribution-packages/release-checklist)
- [](distribution-packages/pypi-sdist-wheel)
- [](distribution-packages/conda)
- [](distribution-packages/ubuntu-ppa)
- [](distribution-packages/windows-and-macos.md)
```{toctree}
:caption: Distributing Built Cantera Packages
:caption: Releasing & Distributing Cantera
:hidden:
:maxdepth: 1
distribution-packages/release-checklist
distribution-packages/pypi-sdist-wheel
distribution-packages/conda
distribution-packages/ubuntu-ppa

4
doc/sphinx/develop/style-guidelines.md
View File

@ -88,8 +88,8 @@ it easier for others to understand your code in the context of Cantera as a whol
### Style Guide
* Style generally follows [PEP8](https://www.python.org/dev/peps/pep-0008/)
* The minimum Python version that Cantera supports is Python 3.8, so code should only
use features added in Python 3.8 or earlier
* The minimum Python version that Cantera supports is Python 3.10, so code should only
use features added in Python 3.10 or earlier
* Please use double quotes in all new Python code
### Sphinx comments

15
doc/sphinx/examples/index.md
View File

@ -81,6 +81,20 @@ interface.
````
## Input File Examples
````{grid} 2 2 3 3
:gutter: 3
```{grid-item-card} YAML
:link: input/index
:link-type: doc
:text-align: center
```
````
% The following pages are generated by sphinx-gallery
```{toctree}
:maxdepth: 2
@ -91,6 +105,7 @@ cxx/index
clib/index
matlab_experimental/index
fortran/index
input/index
```
% The following page is generated by sphinx-tags

5
doc/sphinx/examples/input/covdepsurf.md Normal file
View File

@ -0,0 +1,5 @@
# `covdepsurf.yaml`
```{literalinclude} ../../../../../data/example_data/covdepsurf.yaml
:language: yaml
```

5
doc/sphinx/examples/input/diamond.md Normal file
View File

@ -0,0 +1,5 @@
# `diamond.yaml`
```{literalinclude} ../../../../../data/diamond.yaml
:language: yaml
```

5
doc/sphinx/examples/input/h2o2.md Normal file
View File

@ -0,0 +1,5 @@
# `h2o2.yaml`
```{literalinclude} ../../../../../data/h2o2.yaml
:language: yaml
```

48
doc/sphinx/examples/input/index.md Normal file
View File

@ -0,0 +1,48 @@
# Example Input Files
The following example input files, demonstrate how some of the features of Cantera's
YAML format can be used to define phases, species, and reactions. These files are a
subset of the input files included with Cantera.
[`h2o2.yaml`](h2o2.md)
: A basic gas phase reaction mechanism. Demonstrates multiple phase definitions using
the same set of species, specification of transport properties, and parameters for
the Redlich-Kwong equation of state.
[`diamond.yaml`](diamond.md)
: A heterogenous reaction mechanism. Demonstrates defining surfaces and adjacent bulk
phases and reading species definitions from other input files. This input file is used
in the example [`diamond_cvd.py`](/examples/python/kinetics/diamond_cvd).
[`lithium_ion_battery.yaml`](lithium_ion_battery.md)
: An input file for an LCO/graphite lithium-ion battery. Demonstrates multiple surface
phase definitions, input for the
[`binary-solution-tabulated`](sec-yaml-binary-solution-tabulated) thermo model, and
electrochemical reactions. This input file is used in the example
[`lithium_ion_battery.py`](/examples/python/kinetics/lithium_ion_battery).
[`covdepsurf.yaml`](covdepsurf.md)
: An input file for a surface phase where the non-ideal interactions between species are
accounted for in the calculation of the enthalpy and entropy. Demonstrates the
[`coverage-dependent-surface`](sec-yaml-coverage-dependent-surface) model and the
corresponding [`coverage-dependencies`](sec-yaml-species-coverage) field of the
`species` entry. This input file is used in the example
[`coverage_dependent_surf.py`](/examples/python/thermo/coverage_dependent_surf).
[`oxygen-plasma-itikawa.yaml`](oxygen-plasma-itikawa.md)
: An input file representing some plasma interactions. Demonstrates the setup of a
`plasma` phase, reactions parameterized using the
[`two-temperature-plasma`](sec-yaml-two-temperature-plasma) and
[`electron-collision-plasma`](sec-yaml-electron-collision-plasma) rate types, and the
use of multiple `reactions` sections.
```{toctree}
:maxdepth: 2
:hidden:
h2o2
diamond
lithium_ion_battery
covdepsurf
oxygen-plasma-itikawa
```

5
doc/sphinx/examples/input/lithium_ion_battery.md Normal file
View File

@ -0,0 +1,5 @@
# `lithium_ion_battery.yaml`
```{literalinclude} ../../../../../data/lithium_ion_battery.yaml
:language: yaml
```

5
doc/sphinx/examples/input/oxygen-plasma-itikawa.md Normal file
View File

@ -0,0 +1,5 @@
# `oxygen-plasma-itikawa.yaml`
```{literalinclude} ../../../../../data/example_data/oxygen-plasma-itikawa.yaml
:language: yaml
```

5
doc/sphinx/index.md
View File

@ -1,10 +1,5 @@
# Table of Contents
```{caution}
This page is a work in progress. For documentation and tutorials for Cantera 3.0, please
see <a href="/index.html">this page</a>.
```
```{toctree}
:maxdepth: 1

69
doc/sphinx/install/conda.md
View File

@ -2,40 +2,19 @@
(sec-install-conda)=
Conda is a package manager built by the Anaconda company. There are several
distributions of Python that include `conda`, including [Anaconda][anaconda] and
[miniforge][miniforge]. If you do not have conda installed, we highly recommend using
[miniforge][miniforge].
[Conda](https://docs.conda.io/projects/conda/en/stable/) is a package manager that can
be used to install Python packages and other software. Cantera packages are available
via the `conda-forge` channel, for use with Conda distributions that use that channel.
We highly recommend using the [Miniforge](https://conda-forge.org/download/)
distribution, which configures `conda-forge` as the default channel (in which case you
can omit the argument `--channel conda-forge` from any of the commands below).
[anaconda]: https://www.anaconda.com/download#Downloads
[miniforge]: https://github.com/conda-forge/miniforge?tab=readme-ov-file#install
For more details on how to use Conda, see the
[Conda documentation](https://docs.conda.io/projects/conda/en/latest/user-guide/index.html).
:::{attention}
The *legacy* Matlab Cantera interface is discontinued and removed in Cantera 3.1. Users
requiring support of legacy Matlab Cantera code should continue using Cantera 3.0
packages, or migrate their code base to the experimental Matlab toolbox that is
currently under development.
:::
Both Anaconda and miniforge include the `conda` package manager. The main difference is
that miniforge configures `conda-forge` as the default channel. The `conda-forge`
channel includes many more, up-to-date, packages than the default channel in Anaconda.
For more details on how to use conda, see the
[conda documentation](https://docs.conda.io/projects/conda/en/latest/user-guide/index.html).
For instructions on upgrading an existing conda-based installation of Cantera, see
For instructions on upgrading an existing Conda-based installation of Cantera, see
[Upgrading from an earlier Cantera version](sec-conda-python-upgrade).
:::{tip}
To dramatically improve install speed, we recommend using the `libmamba` dependency
solver. To configure the `libmamba` solver, you can run:
```shell
conda config --set solver libmamba
```
:::
(sec-conda-python-interface)=
## Python interface
@ -49,9 +28,9 @@ Packages are available for the following platforms:
### Option 1: Create a new environment for Cantera
The following instructions will create a conda environment where you can use Cantera
The following instructions will create a Conda environment where you can use Cantera
from Python. For this example, the environment is named `ct-env`. From the command
line (or the Anaconda Prompt on Windows), run:
line (or the Conda Prompt on Windows), run:
```shell
conda create --name ct-env --channel conda-forge cantera ipython matplotlib jupyter
@ -79,7 +58,7 @@ name: ct-env
channels:
- conda-forge
dependencies:
- python # Cantera supports Python 3.8 and up
- python # Cantera supports Python 3.10 and up
- cantera
- ipython # optional (needed for nicer interactive command line)
- jupyter # optional (needed for Jupyter Notebook)
@ -88,7 +67,7 @@ dependencies:
- pandas # optional (needed for pandas interface)
```
From the command line (or the Anaconda Prompt on Windows), change directory into the
From the command line (or the Conda Prompt on Windows), change directory into the
folder where you saved `environment.yaml`:
```shell
@ -135,7 +114,7 @@ to create a new environment.
## Upgrading from an earlier Cantera version
If you already have Cantera installed in a conda environment (named, for example,
If you already have Cantera installed in a Conda environment (named, for example,
`ct-dev`), you can upgrade it to the latest version available by running the commands:
```shell
@ -143,6 +122,13 @@ conda activate ct-dev
conda update --channel conda-forge cantera
```
:::{attention}
This upgrade option will only work if the previous version of Cantera was also installed
from the `conda-forge` channel. If you used the packages from the `cantera` channel that
were also provided for Cantera 3.0 and earlier, this upgrade path will not work and you
should install Cantera in a new Conda environment.
:::
(sec-conda-development-interface)=
## Development (C++ & Fortran 90) Interface
@ -151,7 +137,7 @@ The Cantera development interface provides header files and libraries needed to
your own C++, C, or Fortran applications that link to Cantera. It also provides several
sample programs and build scripts that you can adapt for your own applications.
From the command line (or the Anaconda Prompt on Windows), create a new conda
From the command line (or the Conda Prompt on Windows), create a new Conda
environment named `ct-dev` using:
```shell
@ -233,7 +219,7 @@ Fortran 90 support is not provided for Windows.
### Upgrading from an earlier Cantera version
If you already have the Cantera development interface installed in a conda environment
If you already have the Cantera development interface installed in a Conda environment
(named, for example, `ct-dev`), you can upgrade it to the latest version available by
running the commands:
@ -241,3 +227,12 @@ running the commands:
conda activate ct-dev
conda update --channel conda-forge libcantera-devel
```
## Matlab Interface
:::{attention}
The *legacy* Matlab Cantera interface is discontinued and removed in Cantera 3.1. Users
requiring support of legacy Matlab Cantera code should continue using Cantera 3.0
packages, or migrate their code base to the experimental Matlab toolbox that is
currently under development.
:::

1
doc/sphinx/install/index.md
View File

@ -59,7 +59,6 @@ fedora-rhel
opensuse
gentoo
freebsd
windows
```
## Troubleshooting

18
doc/sphinx/install/pip.md
View File

@ -5,24 +5,18 @@
to install the Cantera Python module from [PyPI](https://pypi.org/project/Cantera/).
:::{caution}
There are a few important limitations to note when Cantera is installed from PyPI:
- These packages are compiled without native HDF5 support. The new options for saving
and restoring `SolutionArray` and flame objects to/from HDF5 files are not available.
- These packages are compiled using single-threaded implementations of LAPACK functions,
and cannot make use of multiple cores to speed up reactor network or flame
simulations.
If you want either of these features, you can install the [Conda](conda) packages
instead.
On Windows, the PyPI packages are compiled using a single-threaded implementation of the
LAPACK library, and cannot make use of multiple cores to speed up reactor network or
flame simulations. If you want to use a version of Cantera with an optimized LAPACK
implementation, you can install the [Conda](conda) package instead.
:::
## Prerequisites
The first step in installing the Cantera Python module using `pip` is to make sure you
have a compatible version of Python installed and are able to run `pip` from the command
line. Packages for Cantera 3.0.0 are available for Python versions 3.8, 3.9, 3.10, and
3.11.
line. Packages for Cantera 3.1.0 are available for Python versions 3.8, 3.9, 3.10, 3.11,
3.12, and 3.13.
If you don't already have Python installed, it can be downloaded from
[python.org](https://www.python.org/) or installed using your operating system's package

18
doc/sphinx/install/ubuntu.md
View File

@ -1,8 +1,8 @@
(sec-install-ubuntu)=
# Ubuntu Packages
As of Cantera 3.0.0, packages are available for Ubuntu 20.04 (Focal Fossa), Ubuntu 22.04
(Jammy Jellyfish), Ubuntu 23.04 (Lunar Lobster), and Ubuntu 23.10 (Mantic Minotaur).
As of Cantera 3.1.0, packages are available for Ubuntu 20.04 (Focal Fossa), Ubuntu 22.04
(Jammy Jellyfish), Ubuntu 24.04 (Noble Numbat) and Ubuntu 24.10 (Oracular Oriole).
Generally, packages are available for the two most-recent LTS releases as well as the
non-LTS releases supported on [Launchpad](https://launchpad.net/ubuntu) at the time of
the Cantera release. To see which Ubuntu releases and Cantera versions are currently
@ -11,12 +11,12 @@ supported, visit the
The available packages are:
- `cantera-python3` - The Cantera Python module for Python 3.
- `python3-cantera` - The Cantera Python module for Python 3.
- `libcantera-dev` - Libraries and header files for compiling your own C, C++ and
Fortran 90 programs that use Cantera.
- `cantera-common` - Cantera data files and example programs
- `libcantera3.0` - The Cantera C++ library, for use by packaged C++ applications.
- `libcantera-fortran3.0` - The Cantera Fortran 90 library, for use by packaged
- `libcantera3.1` - The Cantera C++ library, for use by packaged C++ applications.
- `libcantera-fortran3.1` - The Cantera Fortran 90 library, for use by packaged
Fortran 90 applications.
- `cantera` - A metapackage that will install everything except for the development
files.
@ -33,7 +33,7 @@ sudo apt-add-repository ppa:cantera-team/cantera
To install all of the Cantera packages:
```bash
sudo apt install cantera-python3 libcantera-dev
sudo apt install python3-cantera libcantera-dev
```
or install whichever subset you need by adjusting the above command. The
@ -58,7 +58,7 @@ you have the latest available version installed by running:
```bash
sudo apt update
sudo apt install cantera-python3
sudo apt install python3-cantera
```
If you also have the `libcantera-dev` package installed, it should also be included on
@ -88,6 +88,6 @@ version, run the commands:
```bash
sudo apt-add-repository --remove ppa:cantera-team/cantera-unstable
sudo apt remove cantera cantera-common libcantera-dev cantera-python3
sudo apt install cantera-python3 libcantera-dev
sudo apt remove cantera cantera-common libcantera-dev python3-cantera
sudo apt install python3-cantera libcantera-dev
```

31
doc/sphinx/install/windows.md
View File

@ -1,31 +0,0 @@
(sec-install-windows)=
# Windows Packages
Windows installers are provided for stable versions of Cantera. These installers
provide header/library files that can be used to compile C++ applications.
:::{attention}
The *legacy* Matlab Cantera interface is discontinued and removed in Cantera 3.1. Users
requiring support of legacy Matlab Cantera code should continue using Cantera 3.0
packages, or migrate their code base to the experimental Matlab toolbox that is
currently under development.
:::
:::{seealso}
To install the Cantera Python package, see the [pip](pip) or [conda](conda)
installation instructions. The Python package is required if:
- You need to convert Chemkin-format input files to YAML
- You need to convert legacy CTI or XML input files to YAML
:::
1. **Remove old versions of Cantera**
- Use The Windows "Add/Remove Programs" interface to remove previous versions of
the `Cantera` package.
2. **Install Cantera**
- Go to the [Cantera Releases](https://github.com/Cantera/cantera/releases) page and
download **Cantera-3.0.0-x64.msi**.
- Run the installer and follow the prompts.

4
doc/sphinx/python/index.md
View File

@ -119,6 +119,10 @@ interacting with input data defined using Cantera's [YAML input format](/yaml/in
Classes {py:class}`UnitSystem` and {py:class}`Units` are used for expressing dimensional
quantities in input files.
Several implementations of {py:class}`SystemJacobian` are available for use as
preconditioners for reactor network simulations or linear solvers for the 1D flame simulations (notably, {py:class}`AdaptivePreconditioner` and
{py:class}`EigenSparseDirectJacobian`).
A number of [global functions](sec-python-global-funcs) are provided for managing
locations where Cantera looks for data files, for setting how Cantera handles warnings
and errors, and how some transitional/legacy features are handled.

23
doc/sphinx/python/utilities.rst
View File

@ -31,6 +31,29 @@ Units
.. autoclass:: Units(name)
:no-undoc-members:
.. _sec-python-jacobians:
Jacobians & Preconditioners
---------------------------
SystemJacobian
^^^^^^^^^^^^^^
.. autoclass:: SystemJacobian()
AdaptivePreconditioner
^^^^^^^^^^^^^^^^^^^^^^
.. autoclass:: AdaptivePreconditioner()
BandedJacobian
^^^^^^^^^^^^^^^^^^^^^^
.. autoclass:: BandedJacobian()
EigenSparseDirectJacobian
^^^^^^^^^^^^^^^^^^^^^^^^^
.. autoclass:: EigenSparseDirectJacobian()
.. _sec-python-global-funcs:
Global Functions

7
doc/sphinx/python/zerodim.rst
View File

@ -141,13 +141,6 @@ PressureController
.. autoclass:: PressureController(upstream, downstream, *, name=None, primary=None, K=1.0, edge_attr=None)
:inherited-members:
Preconditioners
---------------
AdaptivePreconditioner
^^^^^^^^^^^^^^^^^^^^^^
.. autoclass:: AdaptivePreconditioner()
Drawing Reactor Networks
------------------------
These functions provide the implementation behind the ``draw`` methods of the

35
doc/sphinx/reference/kinetics/rate-constants.md
View File

@ -475,3 +475,38 @@ Two-temperature plasma reactions can be defined in the YAML format by specifying
[`two-temperature-plasma`](sec-yaml-two-temperature-plasma) as the reaction `type` and
providing the two activation energies as part of the `rate-constant`.
:::
(sec-electron-collision-plasma-rate)=
## Electron Collision Plasma Reactions
The electron collision plasma reaction rate uses the electron collision data and the
electron energy distribution to calculate the reaction rate. Hagelaar and Pitchford
{cite:t}`hagelaar2005` define the reaction rate coefficient (Eqn. 63) as,
$$ k = \gamma \int_0^{\infty} \epsilon \sigma F_0 d\epsilon $$
where $\gamma = \sqrt{2/m_e}$ (Eqn.4 in Hagelaar {cite:t}`hagelaar2015`), $m_e$ [kg] is
the electron mass, $\epsilon$ [J] is the electron energy, $\sigma(\epsilon)$ [m²] is the
reaction collision cross section, $F_0(\epsilon)$ [$\t{J^{-3/2}}$] is the normalized
electron energy distribution function, and $k$ has units of [m³/s].
To recast this in terms of moles rather than molecules, and letting $\epsilon_V$ be the
electron energy expressed in volts, the forward rate coefficient can be rewritten as
$$ k_f = \sqrt{\frac{e}{2 m_e}} N_A
\int_0^{\infty} \sigma(\epsilon_V) F_0(\epsilon_V) d{{\epsilon_V}^2}
$$
where $e$ is the elementary charge [C] and $N_A$ is the Avogadro constant
[$\t{kmol^{-1}}$].
```{versionadded} 3.1
```
:::{admonition} YAML Usage
:class: tip
Electron collision reactions can be defined in the YAML format by specifying
[`electron-collision-plasma`](sec-yaml-electron-collision-plasma) as the reaction `type`
and providing lists with the `cross-sections` and corresponding `energy-levels`.
:::

10
doc/sphinx/reference/onedim/nonlinear-solver.md
View File

@ -65,7 +65,7 @@ $$
J(x) =\pxpy{F(x)}{x}
$$
For the vector-value residual $F(x)$, the Jacobian matrix has elmenets that are
For the vector-value residual $F(x)$, the Jacobian matrix has elements that are
partial derivatives of the residuals with respect to each solution component at each
grid point.
@ -160,7 +160,7 @@ $$
During the search for the correct value of $\lambda$, the value of $\lambda$ starts
at 1, it is adjusted down to a value that keeps the solution within the trust region.
The process then begins for finding $\lambda$, failures result in the damping factor
being reduced by a constant factor. The current factor in Cantera is the $\sqrt{2}$.
being reduced by a constant factor. The current factor in Cantera is the $\sqrt{2}$.
During the damped Newton method, the Jacobian is kept at the $x^{(k)}$ value. This
sometimes can cause issues with convergence if the Jacobian becomes out of date
@ -284,7 +284,7 @@ F(x_n, x_{n+1}) = -\frac{\alpha}{\Delta t}(x_{n+1} - x_n) + F_{ss}(x_{n+1})
$$
For the Newton method, we linearize the residual equation about the solution vector at
the next iteration(not timestep) by using a Taylor series expansion. The linearized
the next iteration (not time step) by using a Taylor series expansion. The linearized
equation is given by:
$$
@ -339,8 +339,8 @@ J_{ss}(x^{(k)}) \Delta x^{(k)} = -\lambda^{(k)} F_{ss}(x^{(k)})
$$
The transient equation has the same form as the steady-state equation, and so the same
damped Newton method can be used to solve the transient problem for a single timestep.
damped Newton method can be used to solve the transient problem for a single time step.
$$
J(x_{n+1}^{(k)}) \Delta x_{n+1}^{(k)} = -\lambda^{(k)} F(x_n, x_{n+1}^{(k)})
$$
$$

1
doc/sphinx/reference/releasenotes/index.md
View File

@ -3,6 +3,7 @@
```{toctree}
:maxdepth: 1
v3.1
v3.0
v2.6
v2.5

22
doc/sphinx/reference/releasenotes/v2.2.md
View File

@ -12,20 +12,20 @@ Published on June 5, 2015 | [Full release on GitHub](https://github.com/Cantera/
New major version. Highlights include:
- Reformulated multicomponent diffusion calculation to improve 1D solver convergence.
- Introduction of `Species` and `Reaction` classes which can be used to construct and modify `ThermoPhase` / `Kinetics` objects on-the-fly, without necessarily using CTI/XML input files. See the new examples [`extract_submechanism.py`](https://cantera.org/documentation/docs-2.2/sphinx/html/cython/examples/kinetics_extract_submechanism.html) and [`mechanism_reduction.py`](https://cantera.org/documentation/docs-2.2/sphinx/html/cython/examples/kinetics_mechanism_reduction.html).
- Introduction of `Species` and `Reaction` classes which can be used to construct and modify `ThermoPhase` / `Kinetics` objects on-the-fly, without necessarily using CTI/XML input files. See the new examples [`extract_submechanism.py`](https://cantera.org/2.2/sphinx/html/cython/examples/kinetics_extract_submechanism.html) and [`mechanism_reduction.py`](https://cantera.org/2.2/sphinx/html/cython/examples/kinetics_mechanism_reduction.html).
- Better handling of CTI and XML files: Parsed CTI and XML files are cached based on modification time and file content, and implicit conversions are done without generating `.xml` files. Phases can be imported directly from XML or CTI strings. Both CTI and XML files can import species and reactions from other CTI or XML files.
- Enable re-initialization of reactor networks, which improves efficiency for integration with CFD-like codes - see the example [`surf_pfr.py`](https://cantera.org/documentation/docs-2.2/sphinx/html/cython/examples/reactors_surf_pfr.html).
- Introduction of a simple radiation model for flames (optically thin, gray gas for CO2 and H2O) - see the example [`diffusion_flame.py`](https://cantera.org/documentation/docs-2.2/sphinx/html/cython/examples/onedim_diffusion_flame.html).
- Efficient sensitivity analysis of 1D flame solutions (see [`flamespeed_sensitivity.py`](https://cantera.org/documentation/docs-2.2/sphinx/html/cython/examples/onedim_flamespeed_sensitivity.html)).
- Added strain rate calculations for diffusion flames (see [`diffusion_flame_extinction.py`](https://cantera.org/documentation/docs-2.2/sphinx/html/cython/examples/onedim_diffusion_flame_extinction.html) and [`diffusion_flame_batch.py`](https://cantera.org/documentation/docs-2.2/sphinx/html/cython/examples/onedim_diffusion_flame_batch.html)).
- Added premixed counterflow flame configuration to Python module (see [`premixed_counterflow_flame.py`](https://cantera.org/documentation/docs-2.2/sphinx/html/cython/examples/onedim_premixed_counterflow_flame.html)).
- Enable re-initialization of reactor networks, which improves efficiency for integration with CFD-like codes - see the example [`surf_pfr.py`](https://cantera.org/2.2/sphinx/html/cython/examples/reactors_surf_pfr.html).
- Introduction of a simple radiation model for flames (optically thin, gray gas for CO2 and H2O) - see the example [`diffusion_flame.py`](https://cantera.org/2.2/sphinx/html/cython/examples/onedim_diffusion_flame.html).
- Efficient sensitivity analysis of 1D flame solutions (see [`flamespeed_sensitivity.py`](https://cantera.org/2.2/sphinx/html/cython/examples/onedim_flamespeed_sensitivity.html)).
- Added strain rate calculations for diffusion flames (see [`diffusion_flame_extinction.py`](https://cantera.org/2.2/sphinx/html/cython/examples/onedim_diffusion_flame_extinction.html) and [`diffusion_flame_batch.py`](https://cantera.org/2.2/sphinx/html/cython/examples/onedim_diffusion_flame_batch.html)).
- Added premixed counterflow flame configuration to Python module (see [`premixed_counterflow_flame.py`](https://cantera.org/2.2/sphinx/html/cython/examples/onedim_premixed_counterflow_flame.html)).
- Allow Sundials to link to external (optimized) BLAS/LAPACK libraries.
- Support for Sundials 2.6.
- Updated Matlab toolbox documentation, which is included in the [online HTML documentation](https://cantera.org/documentation/docs-2.2/sphinx/html/matlab/index.html).
- Updated Matlab toolbox documentation, which is included in the [online HTML documentation](https://cantera.org/2.2/sphinx/html/matlab/index.html).
## Downloads available
- Source code (all platforms) - Download `cantera-2.2.0.tar.gz` from GitHub, and see the [compilation guide](https://cantera.org/documentation/docs-2.2/sphinx/html/compiling.html).
- Windows MSI installers for x86 and x64 systems, including Python modules for Python 2.7, 3.3, and 3.4. See [installation instructions](https://cantera.org/documentation/docs-2.2/sphinx/html/install.html#windows) for details.
- Ubuntu packages for Trusty (14.04 LTS), Utopic, and Vivid via a Launchpad PPA; see [installation instructions](https://cantera.org/documentation/docs-2.2/sphinx/html/install.html#ubuntu)
- OS X Homebrew formula; see [installation instructions](https://cantera.org/documentation/docs-2.2/sphinx/html/install.html#mac-os-x)
- Source code (all platforms) - Download `cantera-2.2.0.tar.gz` from GitHub, and see the [compilation guide](https://cantera.org/2.2/sphinx/html/compiling.html).
- Windows MSI installers for x86 and x64 systems, including Python modules for Python 2.7, 3.3, and 3.4. See [installation instructions](https://cantera.org/2.2/sphinx/html/install.html#windows) for details.
- Ubuntu packages for Trusty (14.04 LTS), Utopic, and Vivid via a Launchpad PPA; see [installation instructions](https://cantera.org/2.2/sphinx/html/install.html#ubuntu)
- OS X Homebrew formula; see [installation instructions](https://cantera.org/2.2/sphinx/html/install.html#mac-os-x)

14
doc/sphinx/reference/releasenotes/v2.3.md
View File

@ -4,15 +4,15 @@ Published on January 19, 2017 | [Full release on GitHub](https://github.com/Cant
## Installation Options
- Conda / anaconda packages for Windows, Linux, and macOS via the `cantera` channel. See [installation instructions](https://cantera.org/documentation/docs-2.3/sphinx/html/install.html) for more details.
- Windows binary installers (downloads below; To use the Matlab toolbox on Windows, install both `Cantera-2.3.0-x64.msi` and one of the Python modules. The Python installers are standalone and do not require the base Cantera package. Installers are available Python 2.7, Python 3.4, Python 3.5, and Python 3.6. See [detailed instructions](https://cantera.org/documentation/docs-2.3/sphinx/html/install.html#windows) for more.
- Ubuntu packages for 16.04 (Xenial Xerus) and 16.10 (Yakkety Yak) are available via the PPA at https://launchpad.net/~speth/+archive/ubuntu/cantera. Additional details available [here](https://cantera.org/documentation/docs-2.3/sphinx/html/install.html#ubuntu).
- Homebrew formula for macOS. See [additonal instructions](https://cantera.org/documentation/docs-2.3/sphinx/html/install.html#homebrew).
- Download and compile the source code. Full instructions [here](https://cantera.org/documentation/docs-2.3/sphinx/html/compiling/index.html).
- Conda / anaconda packages for Windows, Linux, and macOS via the `cantera` channel. See [installation instructions](https://cantera.org/2.3/sphinx/html/install.html) for more details.
- Windows binary installers (downloads below; To use the Matlab toolbox on Windows, install both `Cantera-2.3.0-x64.msi` and one of the Python modules. The Python installers are standalone and do not require the base Cantera package. Installers are available Python 2.7, Python 3.4, Python 3.5, and Python 3.6. See [detailed instructions](https://cantera.org/2.3/sphinx/html/install.html#windows) for more.
- Ubuntu packages for 16.04 (Xenial Xerus) and 16.10 (Yakkety Yak) are available via the PPA at https://launchpad.net/~speth/+archive/ubuntu/cantera. Additional details available [here](https://cantera.org/2.3/sphinx/html/install.html#ubuntu).
- Homebrew formula for macOS. See [additonal instructions](https://cantera.org/2.3/sphinx/html/install.html#homebrew).
- Download and compile the source code. Full instructions [here](https://cantera.org/2.3/sphinx/html/compiling/index.html).
## Documentation
Documentation for Cantera 2.3.0 can be found at <https://cantera.org/documentation/docs-2.3/sphinx/html/index.html>.
Documentation for Cantera 2.3.0 can be found at <https://cantera.org/2.3/sphinx/html/index.html>.
## Changes in Cantera 2.3.0
@ -39,6 +39,6 @@ Highlights are listed here. See the [full changelog](https://github.com/Cantera/
- Use Sundials and Eigen to eliminate the need for bundled LAPACK
- Added Conda build recipe and made binaries available through anaconda.org
- Add support for Sundials 2.7
- Deprecate unused classes, functions, arguments, and constants (see <https://cantera.org/documentation/docs-2.3/doxygen/html/deprecated.html> for details)
- Deprecate unused classes, functions, arguments, and constants (see <https://cantera.org/2.3/doxygen/html/deprecated.html> for details)
- Add notices to documentation for classes with no tests or examples (see https://github.com/Cantera/cantera/issues/267)
- Make clib usable as a pure C (not C++) interface and add tests

6
doc/sphinx/reference/releasenotes/v2.4.md
View File

@ -2,9 +2,9 @@
Published on August 24, 2018 | [Full release on GitHub](https://github.com/Cantera/cantera/releases/tag/v2.4.0)
Cantera 2.4.0 includes [more than 380 commits](https://github.com/Cantera/cantera/compare/v2.3.0...v2.4.0) to the code since 2.3.0, merges more than [70 pull requests](https://github.com/Cantera/cantera/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aclosed+updated%3A%3E%3D2017-01-18+), and [closes almost 60 issues](https://github.com/Cantera/cantera/issues?page=1&q=is%3Aissue+is%3Aclosed+updated%3A%3E%3D2017-01-18&utf8=%E2%9C%93). In this release, we improved the maintainability of Cantera by removing [or deprecating](https://cantera.org/documentation/docs-2.4/doxygen/html/da/d58/deprecated.html) old, untested code, moving the website and Mixmaster to separate repositories, and automating more of the build/testing process. We also added new features to the 1-D reactor code (among other areas), including adding an ionized gas transport class and the `IonFlow` and `BurnerIonFlame` classes, providing better accessing to callbacks during 1-D solutions, and automatically detecting certain common failure conditions of the 1-D solver. This release of Cantera was made possible by contributions from 14 developers: [@speth](https://github.com/speth), [@bryanwweber](https://github.com/bryanwweber), [@BangShiuh](https://github.com/BangShiuh), [@decaluwe](https://github.com/decaluwe), [@wandadars](https://github.com/wandadars), [@jsantner](https://github.com/jsantner), [@arghdos](https://github.com/arghdos), [@rwest](https://github.com/rwest), [@g3bk47](https://github.com/g3bk47), [@awehrfritz](https://github.com/awehrfritz), [@band-a-prend](https://github.com/band-a-prend), [@vdevgan](https://github.com/vdevgan), [@KyleLinevitchJr](https://github.com/KyleLinevitchJr), and [@MarcDuQuesne](https://github.com/MarcDuQuesne).
Cantera 2.4.0 includes [more than 380 commits](https://github.com/Cantera/cantera/compare/v2.3.0...v2.4.0) to the code since 2.3.0, merges more than [70 pull requests](https://github.com/Cantera/cantera/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aclosed+updated%3A%3E%3D2017-01-18+), and [closes almost 60 issues](https://github.com/Cantera/cantera/issues?page=1&q=is%3Aissue+is%3Aclosed+updated%3A%3E%3D2017-01-18&utf8=%E2%9C%93). In this release, we improved the maintainability of Cantera by removing [or deprecating](https://cantera.org/2.4/doxygen/html/da/d58/deprecated.html) old, untested code, moving the website and Mixmaster to separate repositories, and automating more of the build/testing process. We also added new features to the 1-D reactor code (among other areas), including adding an ionized gas transport class and the `IonFlow` and `BurnerIonFlame` classes, providing better accessing to callbacks during 1-D solutions, and automatically detecting certain common failure conditions of the 1-D solver. This release of Cantera was made possible by contributions from 14 developers: [@speth](https://github.com/speth), [@bryanwweber](https://github.com/bryanwweber), [@BangShiuh](https://github.com/BangShiuh), [@decaluwe](https://github.com/decaluwe), [@wandadars](https://github.com/wandadars), [@jsantner](https://github.com/jsantner), [@arghdos](https://github.com/arghdos), [@rwest](https://github.com/rwest), [@g3bk47](https://github.com/g3bk47), [@awehrfritz](https://github.com/awehrfritz), [@band-a-prend](https://github.com/band-a-prend), [@vdevgan](https://github.com/vdevgan), [@KyleLinevitchJr](https://github.com/KyleLinevitchJr), and [@MarcDuQuesne](https://github.com/MarcDuQuesne).
For installation and compilation instructions for Cantera 2.4.0, please see the directions on the [Cantera website](https://cantera.org/install/index.html). In addition to Conda packages, Windows installers, and Ubuntu packages, this release also features the addition of a pre-compiled Matlab toolbox for macOS users, replacing Homebrew as the prefered method of installing Cantera for Matlab on macOS.
In addition to Conda packages, Windows installers, and Ubuntu packages, this release also features the addition of a pre-compiled Matlab toolbox for macOS users, replacing Homebrew as the prefered method of installing Cantera for Matlab on macOS.
Thanks to a small development grant from NumFOCUS (see more about NumFOCUS below), [@bryanwweber](https://github.com/bryanwweber) and [@decaluwe](https://github.com/decaluwe) reorganized and restyled the [Cantera website](https://cantera.org). The website has moved to a [separate repository](https://github.com/Cantera/cantera-website), allowing the website content to be updated without modifications to the main Cantera source code. We also tried to make it easy for all of our users to find what they're looking for quickly, from installation instructions and tutorials for beginners, to advanced examples and API documentation for experienced Cantera programmers. The new website also redirects all traffic to HTTPS, ensuring a secure experience for everyone.
@ -136,7 +136,7 @@ One notable change to the build requirements for Cantera 2.4.0 is that SCons 3.0
- Clean up and test `RedlichKwongMFTP` implementation and remove broken "sanity checks" ([`ecbd819e`](https://github.com/Cantera/cantera/commit/ecbd819e91340ac563ec837bc3347034e69a196f), [`dd521de2`](https://github.com/Cantera/cantera/commit/dd521de25439115e4653389221e844e56c231db3), [`f9d5f16b`](https://github.com/Cantera/cantera/commit/f9d5f16b729bed36009d7ef9ddb4a042f798cfe0), [#267](https://github.com/Cantera/cantera/pull/267), [#436](https://github.com/Cantera/cantera/pull/436), [#438](https://github.com/Cantera/cantera/pull/438))
- Move common PDSS functions into the the `PDSS_Nondimensional` class ([`574462fd`](https://github.com/Cantera/cantera/commit/574462fd3c6d6db6c2d785cc2de0ea745010199c))
- Remove unused thermodynamics models from `ThermoFactory` ([`6154e1b4`](https://github.com/Cantera/cantera/commit/6154e1b4bd417e98a8c94a195794403d633fbd18))
- Deprecate several unused/untested classes. See the [deprecation list](https://cantera.org/documentation/docs-2.4/doxygen/html/da/d58/deprecated.html) for details. ([`2b73fe24`](https://github.com/Cantera/cantera/commit/2b73fe24baa6a10c36dcbc05e4fea2958346da78), [`6d22be2a`](https://github.com/Cantera/cantera/commit/6d22be2a6b282808ad5effa5fd5bd7dca08b0b84), [#267](https://github.com/Cantera/cantera/pull/267))
- Deprecate several unused/untested classes. See the [deprecation list](https://cantera.org/2.4/doxygen/html/da/d58/deprecated.html) for details. ([`2b73fe24`](https://github.com/Cantera/cantera/commit/2b73fe24baa6a10c36dcbc05e4fea2958346da78), [`6d22be2a`](https://github.com/Cantera/cantera/commit/6d22be2a6b282808ad5effa5fd5bd7dca08b0b84), [#267](https://github.com/Cantera/cantera/pull/267))
- Remove unimplemented options from `DebyeHuckel` ([`afafa34c`](https://github.com/Cantera/cantera/commit/afafa34c06640037af82ea1682d6d8c74ae84b36))
- Charge transfer reactions can be set for `surface_reaction`s, not just `edge_reaction`s ([`51f419fb`](https://github.com/Cantera/cantera/commit/51f419fbadef27d318f249c447400a1618a6d151), [#439](https://github.com/Cantera/cantera/pull/439))
- Remove unused members from some thermo classes ([`4818c873`](https://github.com/Cantera/cantera/commit/4818c87344d8d5076ec9dd2808061cdd4a1b38b9), [`6bfd82e0`](https://github.com/Cantera/cantera/commit/6bfd82e0be67a41986c07877ec973a9a97fc0d29), [`90d18dd3`](https://github.com/Cantera/cantera/commit/90d18dd3375c8c87dacecea34e253d5a01d8d8a5), [`c85ba586`](https://github.com/Cantera/cantera/commit/c85ba586d236a27b6aefb8864e3312e5299b0c3a), [`cfc3b728`](https://github.com/Cantera/cantera/commit/cfc3b728f5a7f833c80948d4b6332648882604d6), [`6ca78203`](https://github.com/Cantera/cantera/commit/6ca782030dae74333263d4456e2da7803decdbf7), [`d07908f9`](https://github.com/Cantera/cantera/commit/d07908f9c99e560992098d8ebdb367c6c93dd2a4), [`4b69c7f2`](https://github.com/Cantera/cantera/commit/4b69c7f2654d939204a8b58d8084c70ce3599814), [`572af616`](https://github.com/Cantera/cantera/commit/572af616e7ed767d306fe439c0d7dfaad9e1225b))

4
doc/sphinx/reference/releasenotes/v2.5.md
View File

@ -7,7 +7,7 @@ The Cantera development team is pleased to announce the availability of Cantera
Cantera 2.5 introduces a new input file format, based on the [YAML](https://yaml.org/) data format. This format supersedes the CTI and XML (sometimes called CTML) formats that Cantera has used for many years. Converter scripts from CTI and XML to YAML (`cti2yaml` and `ctml2yaml`), as well as from CHEMKIN (CK) format to YAML (`ck2yaml`), are provided with this release. You can use these scripts in the same way that the old `ck2cti` script was used. All users are encouraged to switch their input files to the new format.
Instructions for installing Cantera 2.5 are available on the [Cantera website](https://cantera.org/install/index.html). Available options include Conda, native installers for Windows and macOS, Ubuntu packages, and compiling from source.
Instructions for installing Cantera 2.5 are available on the [Cantera website](https://github.com/Cantera/cantera-website/tree/v2.5.1/pages/install). Available options include Conda, native installers for Windows and macOS, Ubuntu packages, and compiling from source.
Thank you to the following contributors to Cantera 2.5:
@ -51,7 +51,7 @@ Thank you to the following contributors to Cantera 2.5:
- Remove support for Python 2 ([#560](https://github.com/Cantera/cantera/pull/560), [#611](https://github.com/Cantera/cantera/pull/611))
- Update physical constants based on 2018 CODATA values, and atomic weights to 2018 IUPAC/CIAAW values ([#653](https://github.com/Cantera/cantera/pull/653))
- Deprecated some redundant or rarely-used classes and functions. See the deprecation lists for <a href="https://cantera.org/documentation/docs-2.5/doxygen/html/da/d58/deprecated.html">C++</a> and <a href="https://cantera.org/documentation/docs-2.5/sphinx/html/search.html?q=deprecated&check_keywords=yes&area=default">Python / Matlab / Input files</a>. ([#580](https://github.com/Cantera/cantera/pull/580), [#588](https://github.com/Cantera/cantera/pull/588), [#645](https://github.com/Cantera/cantera/pull/645), [#643](https://github.com/Cantera/cantera/pull/643), [#660](https://github.com/Cantera/cantera/pull/660), [#733](https://github.com/Cantera/cantera/pull/733), [#735](https://github.com/Cantera/cantera/pull/735), [#762](https://github.com/Cantera/cantera/pull/762), [#787](https://github.com/Cantera/cantera/pull/787), [#790](https://github.com/Cantera/cantera/pull/790), [#806](https://github.com/Cantera/cantera/pull/806), [#815](https://github.com/Cantera/cantera/pull/815), [#864](https://github.com/Cantera/cantera/pull/864), [`35be561d9`](https://github.com/Cantera/cantera/commit/35be561d99c4ee8f544db4016849d94bf26b4df6), [`27d9b6413`](https://github.com/Cantera/cantera/commit/27d9b6413a6b12a84947db72658c1785e8c1393f))
- Deprecated some redundant or rarely-used classes and functions. See the deprecation lists for <a href="https://cantera.org/2.5/doxygen/html/da/d58/deprecated.html">C++</a> and <a href="https://cantera.org/2.5/sphinx/html/search.html?q=deprecated&check_keywords=yes&area=default">Python / Matlab / Input files</a>. ([#580](https://github.com/Cantera/cantera/pull/580), [#588](https://github.com/Cantera/cantera/pull/588), [#645](https://github.com/Cantera/cantera/pull/645), [#643](https://github.com/Cantera/cantera/pull/643), [#660](https://github.com/Cantera/cantera/pull/660), [#733](https://github.com/Cantera/cantera/pull/733), [#735](https://github.com/Cantera/cantera/pull/735), [#762](https://github.com/Cantera/cantera/pull/762), [#787](https://github.com/Cantera/cantera/pull/787), [#790](https://github.com/Cantera/cantera/pull/790), [#806](https://github.com/Cantera/cantera/pull/806), [#815](https://github.com/Cantera/cantera/pull/815), [#864](https://github.com/Cantera/cantera/pull/864), [`35be561d9`](https://github.com/Cantera/cantera/commit/35be561d99c4ee8f544db4016849d94bf26b4df6), [`27d9b6413`](https://github.com/Cantera/cantera/commit/27d9b6413a6b12a84947db72658c1785e8c1393f))
- Build and test the sample programs / scripts as part of the CI process ([`1ec9ce2c0`](https://github.com/Cantera/cantera/commit/1ec9ce2c01da81479952dcc12140634d9bd4d9ff), [#649](https://github.com/Cantera/cantera/pull/649), [#776](https://github.com/Cantera/cantera/pull/776), [#874](https://github.com/Cantera/cantera/pull/874), [#883](https://github.com/Cantera/cantera/pull/883), [#905](https://github.com/Cantera/cantera/pull/905), [#923](https://github.com/Cantera/cantera/pull/923), [#927](https://github.com/Cantera/cantera/pull/927))
- Improve handling of phases where the intrinsic state variables are not temperature and density ([#720](https://github.com/Cantera/cantera/pull/720))
- Improve detection and handling of errors in Chemkin input files ([#585](https://github.com/Cantera/cantera/pull/585), [`b2acc43a8`](https://github.com/Cantera/cantera/commit/b2acc43a813fd755a4b60bca87006dc7a72a74a0), [`4f4a2bd07`](https://github.com/Cantera/cantera/commit/4f4a2bd07162a67ca96dcc9f514dbab29beedcfe), [`d04fd8cc3`](https://github.com/Cantera/cantera/commit/d04fd8cc39cb9982aafe7cac28b58174b5fd6a81))

2
doc/sphinx/reference/releasenotes/v2.6.md
View File

@ -84,7 +84,7 @@ The complete list of changes can be found [here](https://github.com/Cantera/cant
## Installation
Instructions for installing Cantera 2.6 are available on the [Cantera website](https://cantera.org/install/index.html). Available options include Conda; pip; native installers for Windows and macOS; packages for Ubuntu, Fedora/Enterprise Linux, Gentoo, and FreeBSD; and compiling from source.
Instructions for installing Cantera 2.6 are available on the [Cantera website](https://github.com/Cantera/cantera-website/tree/v2.6.0/pages/install). Available options include Conda; pip; native installers for Windows and macOS; packages for Ubuntu, Fedora/Enterprise Linux, Gentoo, and FreeBSD; and compiling from source.
## Contributors
This release was made possible by the following contributors: [@anthony-walker](https://github.com/anthony-walker), [@band-a-prend](https://github.com/band-a-prend), [@BangShiuh](https://github.com/BangShiuh), [@blackrabbit17](https://github.com/blackrabbit17), [@bryanwweber](https://github.com/bryanwweber), [@12Chao](https://github.com/12Chao), [@chinahg](https://github.com/chinahg), [@DavidAkinpelu](https://github.com/DavidAkinpelu), [@d-e-t](https://github.com/d-e-t), [@decaluwe](https://github.com/decaluwe), [@dschmider-HSOG](https://github.com/Cantera/cantera/commits?author=dschmider-HSOG), [@g3bk47](https://github.com/g3bk47), [@gkogekar](https://github.com/gkogekar), [@ischoegl](https://github.com/ischoegl), [@jongyoonbae](https://github.com/jongyoonbae), [@lavdwall](https://github.com/lavdwall), [@leesharma](https://github.com/leesharma), [@mefuller](https://github.com/mefuller), [@paulblum](https://github.com/paulblum), [@santoshshanbhogue](https://github.com/santoshshanbhogue), [@speth](https://github.com/speth), [@stijn76](https://github.com/stijn76), [@tpg2114](https://github.com/tpg2114)

85
doc/sphinx/reference/releasenotes/v3.1.md Normal file
View File

@ -0,0 +1,85 @@
# Cantera 3.1.0
Published on December 14, 2024 | [Full release on GitHub](https://github.com/Cantera/cantera/releases/tag/v3.1.0)
The Cantera development team is pleased to announce the availability of Cantera 3.1.0. There have been over [800 commits](https://github.com/Cantera/cantera/wiki/Cantera-3.1.0-Changelog) to Cantera since the last version, 3.0.0, which was released in August 2023. We have closed or merged [128 pull requests](https://github.com/Cantera/cantera/pulls?q=is%3Apr+merged%3A2023-08-23..2024-11-10+is%3Aclosed) and closed [81 issues](https://github.com/Cantera/cantera/issues?q=is%3Aissue+closed%3A2023-08-23..2024-12-14+is%3Aclosed) and [24 enhancement proposals](https://github.com/Cantera/enhancements/issues?q=is:issue+closed:2023-08-23..2024-12-14+is:closed). Instructions for installing Cantera 3.1 are available on the [Cantera website](/install/index).
## Highlights
- Render [examples](/examples/python/index) using Sphinx-gallery ([#1621](https://github.com/Cantera/cantera/pull/1621), [#1681](https://github.com/Cantera/cantera/pull/1681), [#1724](https://github.com/Cantera/cantera/pull/1724), [#1821](https://github.com/Cantera/cantera/pull/1821), [E#88](https://github.com/Cantera/enhancements/issues/88))
- Added visualizations of reactor networks; see [`mix1.py`](/examples/python/reactors/mix1) and [`reactor2.py`](/examples/python/reactors/reactor2) ([E#180](https://github.com/Cantera/enhancements/issues/180), [#1624](https://github.com/Cantera/cantera/pull/1624), [#1714](https://github.com/Cantera/cantera/pull/1714), [#1792](https://github.com/Cantera/cantera/pull/1792), [E#212](https://github.com/Cantera/enhancements/issues/212))
- Added ability to solve diffusion flames on the unstable branch using control of the temperature at two interior points; see [`diffusion_flame_continuation.py`](/examples/python/onedim/diffusion_flame_continuation) ([#1622](https://github.com/Cantera/cantera/pull/1622), [#1779](https://github.com/Cantera/cantera/pull/1779), [#1813](https://github.com/Cantera/cantera/pull/1813))
- Added the [`linear-Burke`](sec-linear-Burke) reaction rate parameterization which models pressure-dependent reactions with collider-specific behavior; see [`shock_tube.py`](/examples/python/kinetics/shock_tube), [`jet_stirred_reactor.py`](/examples/python/kinetics/jet_stirred_reactor), and [`flame_speed.py`](/examples/python/onedim/flame_speed) ([E#157](https://github.com/Cantera/enhancements/issues/157), [#1710](https://github.com/Cantera/cantera/pull/1710), [#1801](https://github.com/Cantera/cantera/pull/1801))
- Major expansion of documentation for [contributing to Cantera](/develop/index) and [understanding its internal workings](/reference/onedim/index) ([E#25](https://github.com/Cantera/enhancements/issues/25), [#1700](https://github.com/Cantera/cantera/pull/1700), [#1757](https://github.com/Cantera/cantera/pull/1757), [#1786](https://github.com/Cantera/cantera/pull/1786))
- Update website structure to keep all version-specific documentation together and simplify URLs ([E#145](https://github.com/Cantera/enhancements/issues/145), [E#146](https://github.com/Cantera/enhancements/issues/146), [#1631](https://github.com/Cantera/cantera/pull/1631), [#1638](https://github.com/Cantera/cantera/pull/1638), [#1647](https://github.com/Cantera/cantera/pull/1647), [#1657](https://github.com/Cantera/cantera/pull/1657), [#1657](https://github.com/Cantera/cantera/pull/1657), [#1737](https://github.com/Cantera/cantera/pull/1737), [#1766](https://github.com/Cantera/cantera/pull/1766), [#1790](https://github.com/Cantera/cantera/pull/1790))
- Significant refactoring of the `clib` interface, which is now declared *experimental* and subject to API changes without receiving deprecation warnings. ([E#211](https://github.com/Cantera/enhancements/issues/211), [E#199](https://github.com/Cantera/enhancements/issues/199), [#1741](https://github.com/Cantera/cantera/pull/1741), [#1752](https://github.com/Cantera/cantera/pull/1752), [#1760](https://github.com/Cantera/cantera/pull/1760), [#1769](https://github.com/Cantera/cantera/pull/1769), [#1773](https://github.com/Cantera/cantera/pull/1773), [#1780](https://github.com/Cantera/cantera/pull/1780))
## New features
- Add electron collision reactions (C++ class {ct}`ElectronCollisionPlasmaRate`) based on cross section data from the LXCat database; see [`plasma.py`](/examples/python/reactors/plasma) ([#1262](https://github.com/Cantera/cantera/pull/1262))
- Added an example demonstrating a 1D packed-bed reactor; see [`1D_packed_bed.py`](/examples/python/reactors/1D_packed_bed) ([E#43](https://github.com/Cantera/enhancements/issues/43))
- Added option to compute diffusive fluxes using mass fraction gradients in the 1D solver ([E#195](https://github.com/Cantera/enhancements/issues/195), [#1668](https://github.com/Cantera/cantera/pull/1668))
- Expose Peng-Robinson EoS parameters to Python interface ([#1664](https://github.com/Cantera/cantera/pull/1664))
- Created a new repository to clearly identify example input data and allow use of larger, more detailed mechanisms ([E#22](https://github.com/Cantera/enhancements/issues/22), [#1689](https://github.com/Cantera/cantera/pull/1689))
- Add HDF5 support to PyPI packages ([E#205](https://github.com/Cantera/enhancements/issues/205), ([#1727](https://github.com/Cantera/cantera/pull/1727))
- Add stack trace option to `CanteraError` for enhanced debugging ([#1730](https://github.com/Cantera/cantera/pull/1730))
- Enable cross compiling support without patches to simplify some package builds ([E#210](https://github.com/Cantera/enhancements/issues/210), [#1749](https://github.com/Cantera/cantera/pull/1749))
- Add support for Python 3.12 ([#1604](https://github.com/Cantera/cantera/pull/1604), [#1648](https://github.com/Cantera/cantera/pull/1648), [#1716](https://github.com/Cantera/cantera/pull/1716))
- Add compatibility with SUNDIALS 7.0 ([#1672](https://github.com/Cantera/cantera/pull/1672))
- Add compatibility with NumPy 2.0 ([#1706](https://github.com/Cantera/cantera/pull/1706), [#1713](https://github.com/Cantera/cantera/pull/1713))
- Support compilation in C++20 mode ([#1739](https://github.com/Cantera/cantera/pull/1739))
- Automatically adjust temperature bounds for low-temperature flames ([#1684](https://github.com/Cantera/cantera/issues/1684), [#1705](https://github.com/Cantera/cantera/pull/1705))
- Add BLAS/LAPACK support for PyPI packages on Linux and macOS ([#1797](https://github.com/Cantera/cantera/pull/1797))
- Add programmatic access to logging information about transport property fits ([#1824](https://github.com/Cantera/cantera/pull/1824))
## Changes to existing capabilities
- Refactored implementation of 1D flame governing equations ([#1595](https://github.com/Cantera/cantera/pull/1595), [#1619](https://github.com/Cantera/cantera/pull/1619))
- Improvements to 1D solver logging ([#1660](https://github.com/Cantera/cantera/pull/1660), [#1759](https://github.com/Cantera/cantera/pull/1759))
- Significant improvements to error messages reported when converting mechanisms using `ck2yaml` ([#1669](https://github.com/Cantera/cantera/pull/1669), [#1736](https://github.com/Cantera/cantera/pull/1736))
- Improved handling of edge cases involving third body colliders and "duplicate" reactions ([#1696](https://github.com/Cantera/cantera/pull/1696))
- Improve distinction between selecting `none` and `default` transport models ([#1680](https://github.com/Cantera/cantera/issues/1680), [#1705](https://github.com/Cantera/cantera/pull/1705))
- Improve error message for flames initialized with bad boundary conditions ([#1694](https://github.com/Cantera/cantera/issues/1694), [#1705](https://github.com/Cantera/cantera/pull/1705))
- Disallow redundant flame grid specification ([#1693](https://github.com/Cantera/cantera/issues/1693), [#1705](https://github.com/Cantera/cantera/pull/1705))
- Simplify YAML input for extensible interface reactions ([#1709](https://github.com/Cantera/cantera/pull/1709))
- Improve consistency of `Func1` API between Matlab and Python interfaces ([#1758](https://github.com/Cantera/cantera/pull/1758), [#1798](https://github.com/Cantera/cantera/pull/1798))
- Use `Solution` objects to store reactor contents ([#1663](https://github.com/Cantera/cantera/pull/1663), [#1685](https://github.com/Cantera/cantera/pull/1685))
- Move locks that prevent adding species to `ThermoPhase` objects that are in use from Python to C++ ([#1686](https://github.com/Cantera/cantera/pull/1686))
- Use Jinja templates in C# `sourcegen` ([#1785](https://github.com/Cantera/cantera/pull/1785))
- Update `ck2yaml` to use `argparse` ([#1616](https://github.com/Cantera/cantera/pull/1616))
- Make names generated for reactor network objects reproducible ([#1765](https://github.com/Cantera/cantera/pull/1765))
- Make generated sources and error messages deterministic ([#1804](https://github.com/Cantera/cantera/pull/1804))
- Remove features deprecated in Cantera 3.0. ([#1605](https://github.com/Cantera/cantera/pull/1605))
- Remove legacy Matlab toolbox ([E#196](https://github.com/Cantera/enhancements/issues/196), [#1670](https://github.com/Cantera/cantera/pull/1670), [#1688](https://github.com/Cantera/cantera/pull/1688))
- Remove `python_minimal` interface ([E#208](https://github.com/Cantera/enhancements/issues/208), [#1745](https://github.com/Cantera/cantera/pull/1745))
- Expanded automated CI testing and other CI maintenance ([#1608](https://github.com/Cantera/cantera/pull/1608), [#1612](https://github.com/Cantera/cantera/pull/1612), [#1630](https://github.com/Cantera/cantera/pull/1630), [#1652](https://github.com/Cantera/cantera/pull/1652), [#1662](https://github.com/Cantera/cantera/pull/1662), [#1671](https://github.com/Cantera/cantera/pull/1671), [#1677](https://github.com/Cantera/cantera/pull/1677), [#1703](https://github.com/Cantera/cantera/pull/1703), [#1738](https://github.com/Cantera/cantera/pull/1738), [#1752](https://github.com/Cantera/cantera/pull/1752), [#1808](https://github.com/Cantera/cantera/pull/1808), [#1815](https://github.com/Cantera/cantera/pull/1815), [#1818](https://github.com/Cantera/cantera/pull/1818))
- Various documentation updates ([#1618](https://github.com/Cantera/cantera/pull/1618), [#1659](https://github.com/Cantera/cantera/pull/1659), [#1702](https://github.com/Cantera/cantera/pull/1702), [#1795](https://github.com/Cantera/cantera/pull/1795), [#1803](https://github.com/Cantera/cantera/pull/1803), [#1807](https://github.com/Cantera/cantera/pull/1807), [#1810](https://github.com/Cantera/cantera/pull/1810), [#1817](https://github.com/Cantera/cantera/pull/1817), [#1826](https://github.com/Cantera/cantera/pull/1826))
- Various build system updates ([#1723](https://github.com/Cantera/cantera/pull/1723), [#1746](https://github.com/Cantera/cantera/pull/1746), [#1750](https://github.com/Cantera/cantera/pull/1750), [#1755](https://github.com/Cantera/cantera/pull/1755), [#1768](https://github.com/Cantera/cantera/pull/1768), [#1782](https://github.com/Cantera/cantera/pull/1782), [#1791](https://github.com/Cantera/cantera/pull/1791), [E#209](https://github.com/Cantera/enhancements/issues/209), [#1820](https://github.com/Cantera/cantera/pull/1820))
- Fix some compiler warnings ([#1729](https://github.com/Cantera/cantera/pull/1729))
- Maintenance of the sdist / PyPI packages ([#1625](https://github.com/Cantera/cantera/pull/1625), [#1708](https://github.com/Cantera/cantera/pull/1708), [#1796](https://github.com/Cantera/cantera/pull/1796))
- Address some website accessibility issues ([E#41](https://github.com/Cantera/enhancements/issues/41), [#1753](https://github.com/Cantera/cantera/pull/1753))
- Complete transition of the Python test suite to use `pytest` instead of the `unittest` module ([#1793](https://github.com/Cantera/cantera/pull/1793))
- Update generated `CMakeLists.txt` files ([#1742](https://github.com/Cantera/cantera/issues/1742), [#1744](https://github.com/Cantera/cantera/pull/1744))
- Provide better error checking and messages in Python `Quantity` class ([#1816](https://github.com/Cantera/cantera/pull/1816))
- Improve error handling with cubic equation solver used for Redlich-Kwong and Peng-Robinson phases ([#1819](https://github.com/Cantera/cantera/pull/1819))
## Bugs fixed
- Fix missing porosity in `PorousMediaBurner.py` ([#1617](https://github.com/Cantera/cantera/pull/1617))
- Fix various issues in the experimental Matlab toolbox and add missing functions ([#1586](https://github.com/Cantera/cantera/pull/1586), [#1701](https://github.com/Cantera/cantera/pull/1701), [#1761](https://github.com/Cantera/cantera/pull/1761))
- Fix converting surface mechanisms that use a separate thermo data file ([#1637](https://github.com/Cantera/cantera/pull/1637))
- Use midpoint properties for diffusion fluxes in 1D solver ([E#187](https://github.com/Cantera/enhancements/issues/187), [#1626](https://github.com/Cantera/cantera/pull/1626))
- Fix access to `Solution` report when using `with_units` ([#1650](https://github.com/Cantera/cantera/pull/1650))
- Prevent segfaults from accessing partially-constructed reactor objects ([#1661](https://github.com/Cantera/cantera/pull/1661))
- Fix setting diffusion flame initial guess from known data ([#1674](https://github.com/Cantera/cantera/issues/1674), [#1705](https://github.com/Cantera/cantera/pull/1705))
- Fix issues with slicing `SolutionArray` ([#1725](https://github.com/Cantera/cantera/pull/1725), [#1726](https://github.com/Cantera/cantera/pull/1726))
- Fix `yaml2ck` handling of multiline `note` fields and phases with no reactions ([#1733](https://github.com/Cantera/cantera/pull/1733))
- Fix a memory leak when reinitializing a reactor using the GMRES sparse solver ([#1732](https://github.com/Cantera/cantera/pull/1732))
- Fix YAML serialization of changes to reaction/species flags with default values that are normally omitted ([#1629](https://github.com/Cantera/cantera/issues/1629), [#1740](https://github.com/Cantera/cantera/pull/1740))
- Fix serialization of `note` fields that can be erroneously interpreted as integers ([#1610](https://github.com/Cantera/cantera/issues/1610), [#1740](https://github.com/Cantera/cantera/pull/1740))
- Fix YAML serialization of multiline strings ([#1695](https://github.com/Cantera/cantera/issues/1695), [#1740](https://github.com/Cantera/cantera/pull/1740))
- Fix garbage collection-related segfault with `CustomRate` ([#1763](https://github.com/Cantera/cantera/pull/1763))
- Fix compatibility with SUNDIALS 6.0 and 6.1 ([#1774](https://github.com/Cantera/cantera/pull/1774))
- Fix overwriting and ordering of components when outputting `SolutionArray` to YAML ([#1775](https://github.com/Cantera/cantera/pull/1775), [#1781](https://github.com/Cantera/cantera/pull/1781))
- Fix use of `kineticsSpeciesIndex` in `diamond_cvd` examples ([#1814](https://github.com/Cantera/cantera/pull/1814))
- Fix spatial scaling in `MultiTransport::getMassFluxes` and `getMolarFluxes` and improve testing of transport calculations ([#1825](https://github.com/Cantera/cantera/pull/1825))
## Contributors
This release was made possible by the following contributors: [@BangShiuh](https://github.com/BangShiuh), [@Naikless](https://github.com/Naikless), [@bryanwweber](https://github.com/bryanwweber), [@corykinney](https://github.com/corykinney), [@cpilko](https://github.com/cpilko), [@d-e-t](https://github.com/d-e-t), [@decaluwe](https://github.com/decaluwe), [@dholland88](https://github.com/dholland88), [@g3bk47](https://github.com/g3bk47), [@guusbertens](https://github.com/guusbertens), [@ischoegl](https://github.com/ischoegl), [@keszybz](https://github.com/keszybz), [@martey](https://github.com/martey), [@matthiasdiener](https://github.com/matthiasdiener), [@mefuller](https://github.com/mefuller), [@pjsingal](https://github.com/pjsingal), [@speth](https://github.com/speth), [@ssun30](https://github.com/ssun30), [@wandadars](https://github.com/wandadars)

1
doc/sphinx/reference/transport/index.md
View File

@ -15,6 +15,7 @@ one another.
interact with one another to determine properties such as viscosity, thermal
conductivity, and diffusion coefficients for a given thermodynamic state.
(sec-species-transport-parameters)=
## Species Transport Parameters
Transport property models in general require parameters that express the effect of each

228
doc/sphinx/userguide/creating-mechanisms.md
View File

@ -15,8 +15,91 @@ phases and interfaces for use in Cantera simulations.
```{seealso}
See the [](input-tutorial) for an introduction to the YAML syntax used by Cantera and
a description of how dimensional values are handled.
See the [](../examples/input/index) for several complete YAML input files demonstrating
a variety of thermodynamic and reaction parameterizations.
```
## General File Structure
The top level of a Cantera [YAML](https://yaml.org/spec/1.2/spec.html#Introduction)
input file is a mapping, which typically includes several keys providing relevant
metadata followed by several sections that provide definitions for
[phases](sec-yaml-guide-phases), [species](sec-yaml-guide-species), and
[reactions](sec-yaml-guide-reactions). In case input data is provided in a unit system
other than Cantera's default, a [`units`](sec-yaml-units) mapping can be provided. The
following is a typical, abbreviated input file (a subset of the `h2o2.yaml` input file
included with Cantera):
```yaml
description: |-
Hydrogen-Oxygen submechanism extracted from GRI-Mech 3.0.
Modified from the original to include N2.
Redlich-Kwong coefficients are based on tabulated critical properties or estimated
according to the method of Joback and Reid, "Estimation of pure-component properties
from group-contributions," Chem. Eng. Comm. 57 (1987) 233-243.
generator: ck2yaml
input-files: [h2o2.inp, gri30_tran.dat]
cantera-version: 2.5.0
date: Wed, 11 Dec 2019 16:59:04 -0500
units: {length: cm, time: s, quantity: mol, activation-energy: cal/mol}
phases:
- name: ohmech
thermo: ideal-gas
species: [H2, O2, OH]
kinetics: gas
state: {T: 300.0, P: 1 atm}
- name: ohmech-RK
thermo: Redlich-Kwong
species: [H2, O2, OH]
kinetics: gas
state: {T: 300.0, P: 1 atm}
species:
- name: O2
composition: {O: 2}
thermo:
model: NASA7
temperature-ranges: [200.0, 1000.0, 3500.0]
data:
- [3.78245636, -2.99673416e-03, 9.84730201e-06, -9.68129509e-09, 3.24372837e-12,
-1063.94356, 3.65767573]
- [3.28253784, 1.48308754e-03, -7.57966669e-07, 2.09470555e-10, -2.16717794e-14,
-1088.45772, 5.45323129]
note: TPIS89
equation-of-state:
model: Redlich-Kwong
a: 1.74102e+12
b: 22.08100907
- name: O
composition: {O: 1}
thermo:
model: NASA7
temperature-ranges: [200.0, 1000.0, 3500.0]
data:
- [3.1682671, -3.27931884e-03, 6.64306396e-06, -6.12806624e-09, 2.11265971e-12,
2.91222592e+04, 2.05193346]
- [2.56942078, -8.59741137e-05, 4.19484589e-08, -1.00177799e-11, 1.22833691e-15,
2.92175791e+04, 4.78433864]
note: L1/90
equation-of-state:
model: Redlich-Kwong
a: 4.74173e+11
b: 10.69952492
reactions:
- equation: 2 O + M <=> O2 + M # Reaction 1
type: three-body
rate-constant: {A: 1.2e+17, b: -1.0, Ea: 0.0}
efficiencies: {H2: 2.4, H2O: 15.4, AR: 0.83}
```
(sec-yaml-guide-phases)=
## Phases
For each phase that appears in a problem, a corresponding entry should be present in the
@ -142,6 +225,24 @@ phases:
...
```
In cases where the element restriction is also being used to select a subset of
reactions, it is usually necessary to use the `declared-species` option and the
`skip-undeclared-third-bodies` flag as well:
```yaml
phases:
- name: gas
thermo: ideal-gas
elements: [O, H, N]
species:
- gri30.yaml/species: all
skip-undeclared-elements: true
skip-undeclared-third-bodies: true
kinetics: bulk
reactions:
- gri30.yaml/reactions: declared-species
```
### Setting the Kinetics Model
The kinetics model to be used, if any, is specified in the `kinetics` field. Supported
@ -206,6 +307,7 @@ specified in the `transport` field. A [complete list of supported models](sec-ya
can be found in the YAML Input File Reference. For most transport models, additional
parameters need to be specified within each species definition.
(sec-yaml-guide-adjacent)=
### Declaring Adjacent Phases
For interface phases (surfaces and edges), the names of phases adjacent to the interface
@ -432,10 +534,14 @@ The number of atoms of an element must be non-negative, except for electrons.
Examples:
```yaml
composition: {C: 1, O: 2} # carbon dioxide
composition: {Ar: 1, E: -2} # Ar++
composition: {Y: 1, Ba: 2, Cu: 3, O: 6.5} # stoichiometric YBCO
composition: {} # A surface species representing an empty site
- name: CO2
composition: {C: 1, O: 2} # carbon dioxide
- name: Ar++
composition: {Ar: 1, E: -2} # Ar++
- name: YBCO
composition: {Y: 1, Ba: 2, Cu: 3, O: 6.5} # stoichiometric YBCO
- name: (s)
composition: {} # A surface species representing an empty site
```
### Thermodynamic Properties
@ -452,14 +558,16 @@ An example `thermo` field using the 7-coefficient NASA polynomials in two temper
regions:
```yaml
thermo:
model: NASA7
temperature-ranges: [200.0, 1000.0, 3500.0]
data:
- [5.14987613, -0.0136709788, 4.91800599e-05, -4.84743026e-08, 1.66693956e-11,
-1.02466476e+04, -4.64130376]
- [0.074851495, 0.0133909467, -5.73285809e-06, 1.22292535e-09, -1.0181523e-13,
-9468.34459, 18.437318]
- name: CH4
composition: {C: 1, H: 4}
thermo:
model: NASA7
temperature-ranges: [200.0, 1000.0, 3500.0]
data:
- [5.14987613, -0.0136709788, 4.91800599e-05, -4.84743026e-08, 1.66693956e-11,
-1.02466476e+04, -4.64130376]
- [0.074851495, 0.0133909467, -5.73285809e-06, 1.22292535e-09, -1.0181523e-13,
-9468.34459, 18.437318]
```
### Species Equation of State
@ -471,6 +579,21 @@ field of the `equation-of-state` field. A
[complete list of equation of state parameterizations](sec-yaml-species-eos) and their
model-specific fields can be found in the YAML Input File Reference.
An example species definition including coefficients for the Redlich-Kwong real gas
model:
```yaml
- name: c12h26
composition: {C: 12, H: 26}
thermo:
model: NASA7
...
equation-of-state:
model: Redlich-Kwong
a: [1.80382e+14, 0]
b: 259.6081315
```
(sec-yaml-guide-species-transport)=
### Species Transport Coefficients
@ -482,16 +605,21 @@ parameters used depend on the transport model specified at the phase level. The
of possible parameters is described in the {ref}`API documentation
<sec-yaml-species-transport>`.
An example of a `transport` entry for a gas-phase species:
An example of a species definition with a gas-phase `transport` entry:
```yaml
transport:
model: gas
geometry: linear
well-depth: 107.4
diameter: 3.458
polarizability: 1.6
rotational-relaxation: 3.8
- name: O2
composition: {O: 2}
thermo:
model: NASA7
...
transport:
model: gas
geometry: linear
well-depth: 107.4
diameter: 3.458
polarizability: 1.6
rotational-relaxation: 3.8
```
(sec-yaml-guide-reactions)=
@ -538,6 +666,11 @@ treated as [`interface-Blowers-Masel`](sec-yaml-interface-Blowers-Masel), and re
involving charge transfer are automatically identified as
[`electrochemical`](sec-yaml-electrochemical-reaction) reactions.
:::{seealso}
See the [reference documentation](sec-yaml-rate-types) for examples of reactions using
each of the reaction rate parameterizations supported by Cantera.
:::
### Arrhenius Expressions
Most reaction types in Cantera are parameterized by one or more modified Arrhenius
@ -570,6 +703,32 @@ by the non-dimensional quantity $[T/(1\;\t{K})]^b$.
The key `E` is used to specify $E_a$.
The following examples show some reaction definitions making use of Arrhenius and
Arrhenius-like rate parameterizations:
```yaml
- equation: H2 + O <=> H + OH
rate-constant: {A: 5.08e+04, b: 2.67, Ea: 6292.0}
- equation: H2O2 (+ M) <=> OH + OH (+ M)
type: falloff
low-P-rate-constant: {A: 2.49e+24, b: -2.3, Ea: 4.8749e+04}
high-P-rate-constant: {A: 2.0e+12, b: 0.9, Ea: 4.8749e+04}
Troe: {A: 0.43, T3: 1.0e-30, T1: 1.0e+30}
efficiencies: {CO2: 1.6, CO: 2.8, H2O2: 7.7, H2: 3.7, H2O: 7.65, N2: 1.5,
O2: 1.2, HE: 0.65}
- equation: CH3 + OH <=> CH2(S) + H2O
type: pressure-dependent-Arrhenius
rate-constants:
- {P: 0.01 atm, A: 4.936e+14, b: -0.669, Ea: -445.8}
- {P: 0.1 atm, A: 1.207e+15, b: -0.778, Ea: -175.6}
- {P: 1.0 atm, A: 5.282e+17, b: -1.518, Ea: 1772.0}
- {P: 10.0 atm, A: 4.788e+23, b: -3.155, Ea: 7003.0}
- {P: 100.0 atm, A: 8.433e+19, b: -1.962, Ea: 8244.0}
- equation: E + O2 + O2 => O2- + O2
type: two-temperature-plasma
rate-constant: {A: 4.2e-27, b: -1.0, Ea-gas: 600, Ea-electron: 700}
```
(sec-yaml-reaction-options)=
### Duplicate Reactions
@ -585,25 +744,38 @@ $$ k_f(T) = \sum_{n=1}^{N} A_n T^{b_n} \exp(-E_n/RT) $$
While Cantera does not provide such a form for reaction rates, it can be implemented by
defining $N$ duplicate reactions, and assigning one rate coefficient in the sum to each
reaction. By adding the field:
reaction. By adding the field **`duplicate: true`** to a reaction entry, then the
reaction not only *may* have a duplicate, it *must*. Any reaction that specifies that it
is a duplicate, but cannot be paired with another reaction in the phase that qualifies
as its duplicate generates an error. The following defines a pair of duplicate
reactions:
```yaml
duplicate: true
- equation: OH + HO2 <=> O2 + H2O
duplicate: true
rate-constant: {A: 1.45e+13, b: 0.0, Ea: -500.0}
- equation: OH + H2O2 <=> HO2 + H2O
duplicate: true
rate-constant: {A: 2.0e+12, b: 0.0, Ea: 427.0}
```
to a reaction entry, then the reaction not only *may* have a duplicate, it *must*. Any
reaction that specifies that it is a duplicate, but cannot be paired with another
reaction in the phase that qualifies as its duplicate generates an error.
### Negative Pre-exponential Factors
If some of the terms in the above sum have negative $A_n$, this scheme fails, since
Cantera normally does not allow negative pre-exponential factors. But if there are
duplicate reactions such that the total rate is positive, then the fact that negative
$A$ parameters are acceptable can be indicated by adding the field:
$A$ parameters are acceptable can be indicated by adding the field
**`negative-A: true`**. For example, consider the following pair of duplicate rates with
one negative rate:
```yaml
negative-A: true
- equation: NH2 + NO2 <=> H2NO + NO
duplicate: true
rate-constant: {A: 1.1e+12, b: 0.11, Ea: -1186.0}
- equation: NH2 + NO2 <=> H2NO + NO
duplicate: true
rate-constant: {A: -4.3e+17, b: -1.874, Ea: 588.0}
negative-A: true
```
### Reaction Orders

3
doc/sphinx/userguide/faq.md
View File

@ -41,6 +41,9 @@ There are a few sites that distribute mechanisms in the Cantera YAML format:
- [CollectionOfMechanisms](https://github.com/jiweiqi/CollectionOfMechanisms) is a
user-maintained GitHub repository of mechanisms that have been obtained from
scientific publications and other sources.
- Stanford University provides the
[Foundational Fuel Chemistry Model Version 2.0](https://web.stanford.edu/group/haiwanglab/FFCM2/)
(FFCM-2) for combustion of H₂, CO, CH₂O, and C₁-C₄ hydrocarbons.
Many research groups maintain pages with mechanisms they developed, provided in the
Chemkin format. These mechanisms can be converted to the Cantera YAML format using the

4
doc/sphinx/userguide/index.md
View File

@ -17,7 +17,7 @@ troubleshooting.
See the [FAQ](faq) for answers to some common issues that arise when using
Cantera. If your question isn't answered here, consider asking us on the
<a href="https://cantera.org/community.html#the-cantera-users-group">Cantera Users' Group</a>.
[Cantera Users' Group](https://cantera.org/community.html#the-cantera-users-group).
## Task Guides
@ -54,7 +54,7 @@ conditions, or calculating the voltage of a Lithium-ion battery as it is dischar
point for writing your own code.
- Finally, if you have trouble using Cantera and can't find an answer here in the
documentation, please visit the
<a href="https://cantera.org/community.html#the-cantera-users-group">Cantera Users' Group</a>.
[Cantera Users' Group](https://cantera.org/community.html#the-cantera-users-group).
```{toctree}
:hidden:

13
doc/sphinx/yaml/ck2yaml.md Normal file
View File

@ -0,0 +1,13 @@
(sec-ck2yaml)=
# Chemkin to YAML conversion
:::{seealso}
For a tutorial, refer to the [](/userguide/ck2yaml-tutorial) page.
:::
```{eval-rst}
.. argparse::
:module: cantera.ck2yaml
:func: create_argparser
:prog: ck2yaml
```

13
doc/sphinx/yaml/ck2yaml.rst
View File

@ -1,13 +0,0 @@
.. _sec-ck2yaml:
**************************
Chemkin to YAML conversion
**************************
.. seealso::
For a tutorial, refer to the :doc:`/userguide/ck2yaml-tutorial` page.
.. argparse::
:module: cantera.ck2yaml
:func: create_argparser
:prog: ck2yaml

13
doc/sphinx/yaml/cti2yaml.md Normal file
View File

@ -0,0 +1,13 @@
(sec-cti2yaml)=
# CTI to YAML conversion
:::{seealso}
For a tutorial, refer to the page [](/userguide/legacy2yaml-tutorial).
:::
```{eval-rst}
.. argparse::
:module: cantera.cti2yaml
:func: create_argparser
:prog: cti2yaml
```

13
doc/sphinx/yaml/cti2yaml.rst
View File

@ -1,13 +0,0 @@
.. _sec-cti2yaml:
***********************
CTI to YAML conversion
***********************
.. seealso::
For a tutorial, refer to the page :doc:`/userguide/legacy2yaml-tutorial`.
.. argparse::
:module: cantera.cti2yaml
:func: create_argparser
:prog: cti2yaml

13
doc/sphinx/yaml/ctml2yaml.md Normal file
View File

@ -0,0 +1,13 @@
(sec-ctml2yaml)=
# CTML to YAML conversion
:::{seealso}
For a tutorial, refer to the page [](/userguide/legacy2yaml-tutorial).
:::
```{eval-rst}
.. argparse::
:module: cantera.ctml2yaml
:func: create_argparser
:prog: ctml2yaml
```

13
doc/sphinx/yaml/ctml2yaml.rst
View File

@ -1,13 +0,0 @@
.. _sec-ctml2yaml:
***********************
CTML to YAML conversion
***********************
.. seealso::
For a tutorial, refer to the page :doc:`/userguide/legacy2yaml-tutorial`.
.. argparse::
:module: cantera.ctml2yaml
:func: create_argparser
:prog: ctml2yaml

30
doc/sphinx/yaml/elements.md Normal file
View File

@ -0,0 +1,30 @@
(sec-yaml-elements)=
# Elements
`element` entries are needed only when defining custom elements that are not standard
chemical elements, or defining specific isotopes.
The fields of an `element` entry are:
`symbol`
: The symbol used for the element, as used when specifying the composition of species.
`atomic-weight`
: The atomic weight of the element, in unified atomic mass units (dalton).
`atomic-number`
: The atomic number of the element. Optional.
`entropy298`
: The standard molar entropy of the element at 298.15 K. Optional.
An example `elements` section:
```yaml
elements:
- symbol: C13
atomic-weight: 13.003354826
atomic-number: 6
- symbol: O-18
atomic-weight: 17.9991603
```

25
doc/sphinx/yaml/elements.rst
View File

@ -1,25 +0,0 @@
.. highlight:: yaml
.. _sec-yaml-elements:
********
Elements
********
``element`` entries are needed only when defining custom elements that are not
standard chemical elements, or defining specific isotopes.
The fields of an ``element`` entry are:
``symbol``
The symbol used for the element, as used when specifying the composition of
species.
``atomic-weight``
The atomic weight of the element, in unified atomic mass units (dalton).
``atomic-number``
The atomic number of the element. Optional.
``entropy298``
The standard molar entropy of the element at 298.15 K. Optional.

100
doc/sphinx/yaml/general.md Normal file
View File

@ -0,0 +1,100 @@
# General Structure
(sec-yaml-sections)=
## Sections
The top level of a Cantera [YAML](https://yaml.org/spec/1.2/spec.html#Introduction)
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 [](sec-yaml-reactions), [](sec-yaml-species), and
[](sec-yaml-elements) to add to a phase. A simple input file has the following
structure:
```yaml
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
```
(sec-yaml-units)=
## Units
While Cantera generally works internally in SI units, input values can be provided using
a number of different units.
Compound units are written using the asterisk (`*`) to indicate multiplication, the
forward slash (`/`) to indicate division, and the caret (`^`) to indicate
exponentiation. Exponents can include negative and decimal values. Standard one-letter
metric prefixes can be applied to any unit. Supported base units are:
- Mass: `g`
- Length: `m`, `micron`, `angstrom`, `Å`
- Time: `s`, `min`, `hr`
- Temperature: `K`, `C`
- Current: `A`
- Quantity: `mol` (gram mole), `gmol`, `mole`, `kmol`, `kgmol`, `molec`
Supported compound units are:
- Energy: `J`, `cal`, `erg`, `eV`
- Activation Energy: `K`, any unit of energy per quantity (`J/kmol`,
`cal/mol`, etc.), or any unit of energy (such as `eV`)
- Force: `N`, `dyn`
- Pressure: `Pa`, `atm`, `bar`, `dyn/cm^2`
- Volume: `m^3`, `liter`, `L`, `l`, `cc`
- Other electrical units: `ohm`, `V`, `coulomb`
Units can be specified on individual input values by placing them after the value,
separated by a space:
```yaml
{A: 1.45e9 cm^3/kmol, b: 0.4, Ea: 21033 kJ/kmol}
```
or by using a `units` mapping:
```yaml
units: {mass: g, quantity: mol, pressure: atm, activation-energy: cal/mol}
```
A `units` mapping will set the default units for all values within the same YAML list or
mapping, including any nested lists and mappings. Units not specified by a mapping use
the values from higher level mappings, or the Cantera defaults if no `units` mapping
specifies applicable units. If a `units` mapping appears in a list, it must be the first
item in that list.
Default units may be set for `mass`, `length`, `time`, `temperature`, `current`,
`quantity`, `pressure`, `energy`, and `activation-energy`. The units `pressure` and
`energy` are used when these units appear explicitly in the units that a value is being
converted to within Cantera. For example, a conversion to `N/m^2` will use the default
units for mass, length, and time, while a conversion to `Pa` will use the default units
for pressure.
Activation energies given in temperature units will be implicitly converted to energy
per quantity by dividing by the gas constant. Activation energies given in pure energy
units such as eV will be converted to energy per quantity by multiplying by the Avogadro
constant. Setting default units for `energy` and `quantity` will determine the default
units of `activation-energy`, which can be overridden by explicitly giving the desired
units of `activation-energy`.

103
doc/sphinx/yaml/general.rst
View File

@ -1,103 +0,0 @@
.. highlight:: yaml
*****************
General Structure
*****************
.. _sec-yaml-sections:
Sections
--------
The top level of a Cantera `YAML <https://yaml.org/spec/1.2/spec.html#Introduction>`__
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. A simple input file has the
following structure::
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
.. _sec-yaml-units:
Units
-----
While Cantera generally works internally in SI units, input values can be
provided using a number of different units.
Compound units are written using the asterisk (``*``) to indicate
multiplication, the forward slash (``/``) to indicate division, and the caret
(``^``) to indicate exponentiation. Exponents can include negative and decimal
values. Standard one-letter metric prefixes can be applied to any unit.
Supported base units are:
- Mass: ``g``
- Length: ``m``, ``micron``, ``angstrom``, ``Å``
- Time: ``s``, ``min``, ``hr``
- Temperature: ``K``, ``C``
- Current: ``A``
- Quantity: ``mol`` (gram mole), ``gmol``, ``mole``, ``kmol``, ``kgmol``, ``molec``
Supported compound units are:
- Energy: ``J``, ``cal``, ``erg``, ``eV``
- Activation Energy: ``K``, any unit of energy per quantity (``J/kmol``,
``cal/mol``, etc.), or any unit of energy (such as `eV`)
- Force: ``N``, ``dyn``
- Pressure: ``Pa``, ``atm``, ``bar``, ``dyn/cm^2``
- Volume: ``m^3``, ``liter``, ``L``, ``l``, ``cc``
- Other electrical units: ``ohm``, ``V``, ``coulomb``
Units can be specified on individual input values by placing them after the
value, separated by a space::
{A: 1.45e9 cm^3/kmol, b: 0.4, Ea: 21033 kJ/kmol}
or by using a ``units`` mapping::
units: {mass: g, quantity: mol, pressure: atm, activation-energy: cal/mol}
A ``units`` mapping will set the default units for all values within the same
YAML list or mapping, including any nested lists and mappings. Units not
specified by a mapping use the values from higher level mappings, or the Cantera
defaults if no ``units`` mapping specifies applicable units. If a ``units``
mapping appears in a list, it must be the first item in that list.
Default units may be set for ``mass``, ``length``, ``time``, ``temperature``,
``current``, ``quantity``, ``pressure``, ``energy``, and ``activation-energy``.
The units ``pressure`` and ``energy`` are used when these units appear
explicitly in the units that a value is being converted to within Cantera. For
example, a conversion to ``N/m^2`` will use the default units for mass, length,
and time, while a conversion to ``Pa`` will use the default units for pressure.
Activation energies given in temperature units will be implicitly converted to energy per
quantity by dividing by the gas constant. Activation energies given in pure energy units
such as eV will be converted to energy per quantity by multiplying by the Avogadro
constant. Setting default units for ``energy`` and ``quantity`` will determine the
default units of ``activation-energy``, which can be overridden by explicitly giving
the desired units of ``activation-energy``.

9
doc/sphinx/yaml/lxcat2yaml.md Normal file
View File

@ -0,0 +1,9 @@
(sec-lxcat2yaml)=
# LXCat to YAML conversion
```{eval-rst}
.. argparse::
:module: cantera.lxcat2yaml
:func: create_argparser
:prog: lxcat2yaml
```

10
doc/sphinx/yaml/lxcat2yaml.rst
View File

@ -1,10 +0,0 @@
.. _sec-lxcat2yaml:
**************************
LXCat to YAML conversion
**************************
.. argparse::
:module: cantera.lxcat2yaml
:func: create_argparser
:prog: lxcat2yaml

984
doc/sphinx/yaml/phases.md Normal file
View File

@ -0,0 +1,984 @@
(sec-yaml-phases)=
# Phase Definitions
A `phase` is a mapping that contains definitions for the elements, species, and
optionally reactions that can take place in that phase. The fields of a `phase` entry
are:
`name`
: String identifier used for the phase. Required.
`elements`
: Specification for the elements present in the phase. This can be:
- Omitted, in which case the standard elements will be added as needed by the species
included in the phase.
- A list of element symbols, which can be either defined in the `elements` section of
the file or taken from the standard elements.
- A list of single-key mappings of section names to lists of element symbols. These
sections can be in the same file as the phase definition, or from another file if
written as `file-path/sectionname`. If a relative path is specified, the directory
containing the current file is searched first, followed by the Cantera data path.
Standard elements can be included by referencing the fictitious section `default`.
(sec-yaml-phase-species)=
`species`
: Specification for the species present in the phase. This can be:
- a list of species that appear in the `species` section of the file.
- The string `all`, to indicate that all species in the `species` section should be
included. This is the default if no `species` entry is present.
- A list of single-key mappings of section names to either the string `all` or a list
of species names. These sections can be in the same file as the phase definition, or
from another file if written as `file-path/sectionname`. If a relative path is
specified, the directory containing the current file is searched first, followed by
the Cantera data path.
Species may be skipped depending on the setting of the `skip-undeclared-elements`
option.
`skip-undeclared-elements`
: If set to `true`, do not add species that contain elements that are not explicitly
included in the phase. The default is `false`, where the presence of such species is
considered an error. Filtering of reactions is controlled by the `declared-species`
option in the [](sec-yaml-phase-reactions) entry and the
`skip-undeclared-third-bodies` flag.
`skip-undeclared-third-bodies`
: If set to `true`, ignore third body efficiencies for species that are not defined in
the phase. The default is `false`, where the presence of such third body
specifications is considered an error.
(sec-yaml-phase-explicit-third-body-duplicates)=
`explicit-third-body-duplicates`
: Specifies how to handle three body reactions with an explicit collider that are
duplicates of a three body reaction with the default collider `M`. This can be:
- `warn`: Issue a warning about such reactions. This is the default.
- `error`: Raise an exception if such reactions are found.
- `mark-duplicate`: Mark the reactions as duplicates. Species production and
consumption rates will reflect the sum of the rates. This option may correspond to
the behavior of software packages that do not check for this kind of duplicate
reaction.
- `modify-efficiency`: Set the efficiency of the explicit third body to zero for the
reaction that gives the rate for the default collider. This option is the most
self-consistent but may not correspond to the intent of the mechanism's authors.
:::{versionadded} 3.1
:::
`state`
: A mapping specifying the thermodynamic state. See [](sec-yaml-setting-state).
`adjacent-phases`
: For interface phases, specification of adjacent phases that participate in reactions
on the interface. This can be:
- a list of phase names that appear in the `phases` section of the file.
- A list of single-key mappings of section names to a list of phase names. These
sections can be in the same file as the current phase definition, or from another
file if written as `file-path/section-name`. If a relative path is specified, the
directory containing the current file is searched first, followed by the Cantera
data path.
(sec-yaml-phase-thermo)=
`thermo`
: String specifying the phase thermodynamic model to be used. Supported model strings
are:
- [`binary-solution-tabulated`](sec-yaml-binary-solution-tabulated)
- [`compound-lattice`](sec-yaml-compound-lattice)
- [`coverage-dependent-surface`](sec-yaml-coverage-dependent-surface)
- [`Debye-Huckel`](sec-yaml-Debye-Huckel)
- [`edge`](sec-yaml-edge)
- [`electron-cloud`](sec-yaml-electron-cloud)
- [`fixed-stoichiometry`](sec-yaml-fixed-stoichiometry)
- [`HMW-electrolyte`](sec-yaml-HMW-electrolyte)
- [`ideal-gas`](sec-yaml-ideal-gas)
- [`ideal-molal-solution`](sec-yaml-ideal-molal-solution)
- [`ideal-condensed`](sec-yaml-ideal-condensed)
- [`ideal-solution-VPSS`](sec-yaml-ideal-solution-VPSS)
- [`ideal-surface`](sec-yaml-ideal-surface)
- [`lattice`](sec-yaml-lattice)
- [`liquid-water-IAPWS95`](sec-yaml-liquid-water-IAPWS95)
- [`Margules`](sec-yaml-Margules)
- [`Peng-Robinson`](sec-yaml-Peng-Robinson)
- [`plasma`](sec-yaml-plasma)
- [`pure-fluid`](sec-yaml-pure-fluid)
- [`Redlich-Kister`](sec-yaml-Redlich-Kister)
- [`Redlich-Kwong`](sec-yaml-Redlich-Kwong)
(sec-yaml-phase-kinetics)=
`kinetics`
: String specifying the kinetics model to be used. Supported model strings are:
- `none`
- `bulk` ({ct}`details <BulkKinetics>`)
- `gas` (alias for `bulk`)
- `surface` ({ct}`details <InterfaceKinetics>`)
- `edge` ({ct}`details <EdgeKinetics>`)
(sec-yaml-phase-reactions)=
`reactions`
: Source of reactions to include in the phase, if a kinetics model has been specified.
This can be:
- The string `all`, which indicates that all reactions from the `reactions` section of
the file should be included. This is the default if no `reactions` entry is present.
- The string `declared-species`, which indicates that all reactions from the
`reactions` section involving only species present in the phase should be included.
- The string `none`, which indicates that no reactions should be added. This can be
used if reactions will be added programmatically after the phase is constructed.
- A list of sections from which to include reactions. These sections can be in the
same file as the phase definition, or from another file if written as
`file-path/sectionname`. If a relative path is specified, the directory containing
the current file is searched first, followed by the Cantera data path.
- A list of single-key mappings of section names to rules for adding reactions, where
for each section name, that rule is either `all` or `declared-species` and is
applied as described above.
`Motz-Wise`
: Boolean indicating whether the Motz-Wise correction should be applied to sticking
reactions. Applicable only to interface phases. The default is `false`. The value set
at the phase level may be overridden on individual reactions.
(sec-yaml-phase-transport)=
`transport`
: String specifying the transport model to be used. Supported model strings are:
- `none`
- `high-pressure`: A model for high-pressure gas transport properties based on a
method of corresponding states ({ct}`details <HighPressureGasTransport>`)
- `ionized-gas`: A model implementing the Stockmayer-(n,6,4) model for transport of
ions in a gas ({ct}`details <IonGasTransport>`)
- `mixture-averaged`: The mixture-averaged transport model for ideal gases
({ct}`details <MixTransport>`)
- `mixture-averaged-CK`: The mixture-averaged transport model for ideal gases,
using polynomial fits corresponding to Chemkin-II ({ct}`details <MixTransport>`)
- `multicomponent`: The multicomponent transport model for ideal gases
({ct}`details <MultiTransport>`)
- `multicomponent-CK`: The multicomponent transport model for ideal gases, using
polynomial fits corresponding to Chemkin-II ({ct}`details <MultiTransport>`)
- `unity-Lewis-number`: A transport model for ideal gases, where diffusion
coefficients for all species are set so that the Lewis number is 1
({ct}`details <UnityLewisTransport>`)
- `water`: A transport model for pure water applicable in both liquid and vapor
phases ({ct}`details <WaterTransport>`)
(sec-yaml-setting-state)=
## Setting the state
The state of a `phase` can be set using two properties to set the thermodynamic state,
plus the composition.
The composition can be set using one of the following fields, depending on the phase
type. The composition is specified as a mapping of species names to values. Where
necessary, the values will be automatically normalized.
- `mass-fractions` or `Y`
- `mole-fractions` or `X`
- `coverages`
- `molalities` or `M`
The thermodynamic state can be set using the following property pairs, with some
exceptions for phases where setting that property pair is not implemented. All
properties are on a per unit mass basis where relevant:
- `T` and `P`
- `T` and `D`
- `T` and `V`
- `H` and `P`
- `U` and `V`
- `S` and `V`
- `S` and `P`
- `S` and `T`
- `P` and `V`
- `U` and `P`
- `V` and `H`
- `T` and `H`
- `S` and `H`
- `D` and `P`
The following synonyms are also implemented for use in any of the pairs:
- `temperature`, `T`
- `pressure`, `P`
- `enthalpy`, `H`
- `entropy`, `S`
- `int-energy`, `internal-energy`, `U`
- `specific-volume`, `V`
- `density`, `D`
(sec-yaml-phase-thermo-models)=
## Phase thermodynamic models
(sec-yaml-binary-solution-tabulated)=
### `binary-solution-tabulated`
A phase representing a binary solution where the excess enthalpy and entropy are
interpolated between tabulated values as a function of mole fraction, as
{ct}`described here <BinarySolutionTabulatedThermo>`.
Includes the fields of [](sec-yaml-ideal-condensed), plus:
`tabulated-species`
: The name of the species to which the tabulated enthalpy and entropy is added.
`tabulated-thermo`
: A mapping containing three (optionally four) lists of equal lengths:
`mole-fractions`
: A list of mole fraction values for the tabulated species.
`enthalpy`
: The extra molar enthalpy to be added to the tabulated species at these mole
fractions.
`entropy`
: The extra molar entropy to be added to the tabulated species at these mole
fractions.
`molar-volume`
: The molar volume of the phase at these mole fractions. This input is optional.
```yaml
- name: graphite-anode
thermo: binary-solution-tabulated
species: ["Li[anode]", "V[anode]"]
standard-concentration-basis: unity
tabulated-species: Li[anode]
units: {energy: J, quantity: mol, pressure: atm}
tabulated-thermo:
mole-fractions: [5.75000E-03, 1.25841E-01, 2.45932E-01, 3.66023E-01,
4.86114E-01, 6.06205E-01, 7.26295E-01]
enthalpy: [-6.40692E+04, -9.69664E+03, -8.31339E+03, -7.69063E+03,
-3.94568E+03, -2.01329E+03, -1.59649E+03]
entropy: [3.05724E+01, 2.53501E+01, 1.27000E+01, 1.21865E+01, 1.70474E+01,
1.92980E+01, 1.92885E+01]
state: {T: 300, P: 1, X: {"Li[anode]": 0.3, "V[anode]": 0.7}}
```
:::{versionadded} 2.5
:::
(sec-yaml-compound-lattice)=
### `compound-lattice`
A phase that is comprised of a fixed additive combination of other lattice phases, as
{ct}`described here <LatticeSolidPhase>`.
Additional fields:
`composition`
: A mapping of component phase names to their relative stoichiometries.
Example:
```yaml
- name: Li7Si3_and_Interstitials(S)
elements: [Li, Si]
thermo: compound-lattice
composition: {Li7Si3(s): 1.0, Li7Si3-interstitial: 1.0}
```
(sec-yaml-coverage-dependent-surface)=
### `coverage-dependent-surface`
A coverage-dependent surface phase. That is, a surface phase where the enthalpy,
entropy, and heat capacity of each species may depend on its coverage and the
coverage of other species in the phase. Full details are
{ct}`described here <CoverageDependentSurfPhase>`. The majority of coverage dependency
parameters are provided in the species entry as
[described here](sec-yaml-species-coverage).
Additional fields:
`site-density`
: The molar density of surface sites.
`reference-state-coverage`
: The reference state coverage denoting the low-coverage limit (ideal-surface)
thermodynamic properties.
Example:
```yaml
- name: covdep
thermo: coverage-dependent-surface
species: [Pt, OC_Pt, CO2_Pt, C_Pt, O_Pt]
state:
T: 500.0
P: 1.01325e+05
coverages: {Pt: 0.5, OC_Pt: 0.5, CO2_Pt: 0.0, C_Pt: 0.0, O_Pt: 0.0}
site-density: 2.72e-09
reference-state-coverage: 0.22
```
:::{versionadded} 3.0
:::
(sec-yaml-debye-huckel)=
### `Debye-Huckel`
A dilute liquid electrolyte which obeys the Debye-Hückel formulation for nonideality as
{ct}`described here <DebyeHuckel>`. Additional parameters for this model are contained
in the `activity-data` field:
`activity-data`
: The activity data field contains the following fields:
`model`
: One of `dilute-limit`, `B-dot-with-variable-a`,
`B-dot-with-common-a`, `beta_ij`, or `Pitzer-with-beta_ij`
`A_Debye`
: The value of the Debye "A" parameter, or the string `variable` to use a calculation
based on the water equation of state. Defaults to the constant value of 1.172576
kg^0.5/gmol^0.5, a nominal value for water at 298 K and 1 atm.
`B_Debye`
: The Debye "B" parameter. Defaults to 3.2864e+09 kg^0.5/gmol^0.5/m, a nominal
value for water.
`max-ionic-strength`
: The maximum ionic strength
`use-Helgeson-fixed-form`
: Boolean, `true` or `false`
`default-ionic-radius`
: Ionic radius to use for species where the ionic radius has not been specified.
`B-dot`
: The value of B-dot.
`beta`
: List of mappings providing values of $\beta_{ij}$ for different species pairs. Each
mapping contains a `species` key that contains a list of two species names, and a
`beta` key that contains the corresponding value of $\beta_{ij}$.
Example:
```yaml
- name: debye-huckel-pitzer-beta_ij-IAPWS
species:
- water_IAPWS: [H2O(L)]
- species_waterSolution: [Na+, Cl-, H+, OH-, NaCl(aq), NaOH(aq)]
thermo: Debye-Huckel
activity-data:
model: Pitzer-with-beta_ij
A_Debye: variable
B_Debye: 3.28640E9 kg^0.5/gmol^0.5/m
default-ionic-radius: 3.042843 angstrom
max-ionic-strength: 3.0
beta:
- species: [H+, Cl-]
beta: 0.27
- species: [Na+, Cl-]
beta: 0.15
- species: [Na+, OH-]
beta: 0.06
state:
T: 300.0 K
P: 1.01325e+05 Pa
molalities: {Na+: 3.0, Cl-: 3.0, H+: 1.0499e-08, OH-: 1.3765e-06,
NaCl(aq): 0.98492, NaOH(aq): 3.8836e-06}
```
In addition, the Debye-Hückel model uses several species-specific properties which may
be defined in the `Debye-Huckel` field of the *species* entry. These properties are:
`ionic-radius`
: Size of the species.
`electrolyte-species-type`
: One of `solvent`, `charged-species`, `weak-acid-associated`, `strong-acid-associated`,
`polar-neutral`, or `nonpolar-neutral`. The type `solvent` is the default for the
first species in the phase. The type `charged-species` is the default for species with
a net charge. Otherwise, the default is and `nonpolar-neutral`.
`weak-acid-charge`
: Charge to use for species that can break apart into charged species.
Example:
```yaml
species:
- name: NaCl(aq)
composition: {Na: 1, Cl: 1}
thermo:
model: piecewise-Gibbs
h0: -96.03E3 cal/mol
dimensionless: true
data: {298.15: -174.5057463, 333.15: -174.5057463}
equation-of-state:
model: constant-volume
molar-volume: 1.3
Debye-Huckel:
ionic-radius: 4 angstrom
electrolyte-species-type: weak-acid-associated
weak-acid-charge: -1.0
```
(sec-yaml-edge)=
### `edge`
A one-dimensional edge between two surfaces, as {ct}`described here <EdgePhase>`.
Additional fields:
`site-density`
: The molar density of sites per unit length along the edge
Example:
```yaml
- name: tpb
thermo: edge
adjacent-phases: [metal, metal_surface, oxide_surface]
elements: [H, O]
species: [(tpb)]
kinetics: edge
reactions: [tpb-reactions]
state: {T: 1073.15, coverages: {(tpb): 1.0}}
site-density: 5.0e-17 mol/cm
```
(sec-yaml-electron-cloud)=
### `electron-cloud`
A phase representing an electron cloud, such as conduction electrons in a metal,
as {ct}`described here <MetalPhase>`.
Additional fields:
`density`
: The density of the bulk metal
Example:
```yaml
- name: metal
thermo: electron-cloud
elements: [E]
species: [electron]
state:
T: 1073.15
X: {electron: 1.0}
density: 9 g/cm^3
```
(sec-yaml-fixed-stoichiometry)=
### `fixed-stoichiometry`
An incompressible phase with fixed composition, as {ct}`described here <StoichSubstance>`.
Example:
```yaml
- name: diamond
thermo: fixed-stoichiometry
elements: [C]
species: [C(d)]
```
(sec-yaml-hmw-electrolyte)=
### `HMW-electrolyte`
A dilute or concentrated liquid electrolyte phase that obeys the Pitzer formulation for
nonideality, as {ct}`described here <HMWSoln>`.
Additional parameters for this model are contained in the `activity-data` field:
`activity-data`
: The activity data field contains the following fields:
`temperature-model`
: The form of the Pitzer temperature model. One of `constant`, `linear` or `complex`.
The default is `constant`.
`A_Debye`
: The value of the Debye "A" parameter, or the string `variable` to use a calculation
based on the water equation of state. The default is 1.172576 kg^0.5/gmol^0.5, a
nominal value for water at 298 K and 1 atm.
`max-ionic-strength`
: The maximum ionic strength
`interactions`
: A list of mappings, where each mapping describes a binary or ternary interaction
among species. Fields of this mapping include:
`species`
: A list of one to three species names
`beta0`
: The $\beta^{(0)}$ parameters for an cation/anion interaction.
1, 2, or 5 values depending on the value of `temperature-model`.
`beta1`
: The $\beta^{(1)}$ parameters for an cation/anion interaction.
1, 2, or 5 values depending on the value of `temperature-model`.
`beta2`
: The $\beta^{(2)}$ parameters for an cation/anion interaction.
1, 2, or 5 values depending on the value of `temperature-model`.
`Cphi`
: The $C^\phi$ parameters for an cation/anion interaction.
1, 2, or 5 values depending on the value of `temperature-model`.
`alpha1`
: The $\alpha^{(1)}$ parameter for an cation/anion interaction.
`alpha2`
: The $\alpha^{(2)}$ parameter for an cation/anion interaction.
`theta`
: The $\theta$ parameters for a like-charged binary interaction.
1, 2, or 5 values depending on the value of `temperature-model`.
`lambda`
: The $\lambda$ parameters for binary interactions involving at least one neutral
species. 1, 2, or 5 values depending on the value of `temperature-model`.
`psi`
: The $\Psi$ parameters for ternary interactions involving three charged species.
1, 2, or 5 values depending on the value of `temperature-model`.
`zeta`
: The $\zeta$ parameters for ternary interactions involving one neutral species. 1,
2, or 5 values depending on the value of `temperature-model`.
`mu`
: The $\mu$ parameters for a neutral species self-interaction.
1, 2, or 5 values depending on the value of `temperature-model`.
`cropping-coefficients`
: Parameters in the molality exponential cutoff treatment
`ln_gamma_k_min`
: Default -5.0.
`ln_gamma_k_max`
: Default 15.0.
`ln_gamma_o_min`
: Default -6.0.
`ln_gamma_o_max`
: Default 3.0.
Example:
```yaml
- name: NaCl_electrolyte
thermo: HMW-electrolyte
activity-data:
temperature-model: complex
A_Debye: 1.175930 kg^0.5/gmol^0.5
interactions:
- species: [Na+, Cl-]
beta0: [0.0765, 0.008946, -3.3158E-6, -777.03, -4.4706]
beta1: [0.2664, 6.1608E-5, 1.0715E-6, 0.0, 0.0]
beta2: [0.0, 0.0, 0.0, 0.0, 0.0]
Cphi: [0.00127, -4.655E-5, 0.0, 33.317, 0.09421]
alpha1: 2.0
- species: [H+, Cl-]
beta0: [0.1775]
beta1: [0.2945]
beta2: [0.0]
Cphi: [0.0008]
alpha1: 2.0
- species: [Na+, OH-]
beta0: 0.0864
beta1: 0.253
beta2: 0.0
Cphi: 0.0044
alpha1: 2.0
alpha2: 0.0
- {species: [Cl-, OH-], theta: -0.05}
- {species: [Na+, Cl-, OH-], psi: -0.006}
- {species: [Na+, H+], theta: 0.036}
- {species: [Cl-, Na+, H+], psi: [-0.004]}
```
(sec-yaml-ideal-gas)=
### `ideal-gas`
A mixture which obeys the ideal gas law, as {ct}`described here <IdealGasPhase>`.
Example:
```yaml
- name: ohmech
thermo: ideal-gas
species: [H2, H, O, O2, OH, H2O, HO2, H2O2, AR, N2]
kinetics: gas
transport: mixture-averaged
state: {T: 300.0, P: 1 atm}
```
(sec-yaml-ideal-molal-solution)=
### `ideal-molal-solution`
An ideal solution based on the mixing-rule assumption that all molality-based activity
coefficients are equal to one, as {ct}`described here <IdealMolalSoln>`.
Additional fields:
`standard-concentration-basis`
: A string specifying the basis for the standard concentration. One of `unity`,
`species-molar-volume`, or `solvent-molar-volume`.
`cutoff`
: Parameters for cutoff treatments of activity coefficients
`model`
: `poly` or `polyExp`
`gamma_o`
: gamma_o value for the cutoff process at the zero solvent point
`gamma_k`
: gamma_k minimum for the cutoff process at the zero solvent point
`X_o`
: value of the solute mole fraction that centers the cutoff polynomials
for the cutoff = 1 process
`c_0`
: Parameter in the polyExp cutoff treatment having to do with rate of
exponential decay
`slope_f`
: Parameter in the `polyExp` cutoff treatment
`slope_g`
: Parameter in the `polyExp` cutoff treatment
Example:
```yaml
- name: NaCl_electrolyte
species: [H2O(L), Cl-, H+, Na+, OH-]
thermo: ideal-molal-solution
standard-concentration-basis: solvent-molar-volume
cutoff:
model: polyexp
gamma_o: 0.0001
gamma_k: 10.0
X_o: 0.2
c_0: 0.05
slope_f: 0.6
slope_g: 0.0
state: {T: 298.15 K, P: 1.01325e+05 Pa,
molalities: {Na+: 6.0954, Cl-: 6.0954, H+: 2.1628e-09, OH-: 1.3977e-06}}
```
(sec-yaml-ideal-condensed)=
### `ideal-condensed`
An ideal liquid or solid solution as {ct}`described here <IdealSolidSolnPhase>`.
Additional fields:
`standard-concentration-basis`
: A string specifying the basis for the standard concentration. One of
`unity`, `species-molar-volume`, or `solvent-molar-volume`.
Example:
```yaml
- name: electrolyte
thermo: ideal-condensed
species: ['C3H4O3[elyt]', 'C4H6O3[elyt]', 'Li+[elyt]', 'PF6-[elyt]']
state:
X: {'C3H4O3[elyt]': 0.47901, 'C4H6O3[elyt]': 0.37563, 'Li+[elyt]': 0.07268,
'PF6-[elyt]': 0.07268}
standard-concentration-basis: unity
```
(sec-yaml-ideal-solution-vpss)=
### `ideal-solution-VPSS`
An ideal solution model using variable pressure standard state methods as
{ct}`described here <IdealSolnGasVPSS>`.
Additional fields:
`standard-concentration-basis`
: A string specifying the basis for the standard concentration. One of
`unity`, `species-molar-volume`, or `solvent-molar-volume`.
Example:
```yaml
- name: NaCl_electrolyte
species: [H2O(L), Na+, Cl-, H+, OH-]
thermo: ideal-solution-VPSS
standard-concentration-basis: solvent-molar-volume
```
(sec-yaml-ideal-surface)=
### `ideal-surface`
An ideal surface between two bulk phases, as {ct}`described here <SurfPhase>`.
Additional fields:
`site-density`
: The molar density of surface sites
Example:
```yaml
- name: Pt_surf
thermo: ideal-surface
adjacent-phases: [gas]
elements: [Pt, H, O, C]
species: [PT(S), H(S), H2O(S), OH(S), CO(S), CO2(S), CH3(S), CH2(S)s,
CH(S), C(S), O(S)]
kinetics: surface
reactions: all
state:
T: 900.0
coverages: {O(S): 0.0, PT(S): 0.5, H(S): 0.5}
site-density: 2.7063e-09
```
(sec-yaml-lattice)=
### `lattice`
A simple thermodynamic model for a bulk phase, assuming an incompressible lattice of
solid atoms, as {ct}`described here <LatticePhase>`.
Additional fields:
`site-density`
: The molar density of lattice sites
Example:
```yaml
- name: oxide_bulk
thermo: lattice
species: [Ox, VO**]
state: {T: 1073.15, P: 1.01325e+05, X: {Ox: 0.95, VO**: 0.05}}
site-density: 0.0176 mol/cm^3
```
(sec-yaml-liquid-water-iapws95)=
### `liquid-water-IAPWS95`
An implementation of the IAPWS95 equation of state for water {cite:p}`wagner2002`, for
the liquid region only as {ct}`described here <WaterSSTP>`.
Example:
```yaml
- name: liquid-water-IAPWS95
species: [H2O]
thermo: liquid-water-IAPWS95
state: {T: 300.0, P: 1.01325e+05}
```
(sec-yaml-margules)=
### `Margules`
A phase employing the Margules approximation for the excess Gibbs free energy, as
{ct}`described here <MargulesVPSSTP>`.
Additional fields:
`interactions`
: A list of mappings, where each mapping has the following fields:
`species`
: A list of two species names
`excess-enthalpy`
: A list of two values specifying the first and second excess enthalpy coefficients
for the interaction of the specified species. Defaults to [0, 0].
`excess-entropy`
: A list of two values specifying the first and second excess entropy coefficients for
the interaction of the specified species. Defaults to [0, 0].
`excess-volume-enthalpy`
: A list of two values specifying the first and second enthalpy coefficients for the
excess volume interaction of the specified species. Defaults to [0, 0].
`excess-volume-entropy`
: A list of two values specifying the first and second entropy coefficients for the
excess volume interaction of the specified species. Defaults to [0, 0].
Example:
```yaml
- name: MoltenSalt_electrolyte
species: [LiCl(L), KCl(L)]
thermo: Margules
interactions:
- species: [KCl(L), LiCl(L)]
excess-enthalpy: [-17570. J/gmol, -377 J/gmol]
excess-entropy: [-7.627 J/gmol/K, 4.958 J/gmol/K]
```
(sec-yaml-peng-robinson)=
### `Peng-Robinson`
A multi-species real gas following the Peng-Robinson equation of state, as
{ct}`described here <PengRobinson>`.
The parameters for each species are contained in the corresponding species
entries. See [Peng-Robinson species equation of state](sec-yaml-eos-peng-robinson).
Example:
```yaml
- name: CO2-PR
species: [CO2, H2O, H2, CO, CH4, O2, N2]
thermo: Peng-Robinson
kinetics: bulk
state: {T: 300, P: 1 atm, mole-fractions: {CO2: 0.99, H2: 0.01}}
```
:::{versionadded} 3.0
:::
(sec-yaml-plasma)=
### `plasma`
A phase for plasma. This phase handles plasma properties such as the electron energy
distribution and electron temperature with different models as
{ct}`described here <PlasmaPhase>`.
Additional fields:
`electron-energy-distribution`
: A mapping with the following fields:
`type`
: String specifying the type of the electron energy distribution to be used.
Supported model strings are:
- `isotropic`
- `discretized`
`shape-factor`
: A constant in the isotropic distribution, which is shown as x in the detailed
description of this class. The value needs to be a positive number. This field is
only used with `isotropic`. Defaults to 2.0.
`mean-electron-energy`
: Mean electron energy of the isotropic distribution. The default sets the electron
temperature equal gas temperature and uses the corresponding electron energy as mean
electron energy. This field is only used with `isotropic`.
`energy-levels`
: A list of values specifying the electron energy levels. The default uses 1001 equal
spaced points from 0 to 1 eV.
`distribution`
: A list of values specifying the discretized electron energy distribution. This field
is only used with `discretized`.
`normalize`
: A flag specifying whether normalizing the discretized electron energy distribution
or not. This field is only used with `discretized`. Defaults to `true`.
Examples:
```yaml
- name: isotropic-electron-energy-plasma
thermo: plasma
kinetics: gas
transport: ionized-gas
electron-energy-distribution:
type: isotropic
shape-factor: 2.0
mean-electron-energy: 1.0 eV
energy-levels: [0.0, 0.1, 1.0, 10.0]
- name: discretized-electron-energy-plasma
thermo: plasma
kinetics: gas
transport: ionized-gas
electron-energy-distribution:
type: discretized
energy-levels: [0.0, 0.1, 1.0, 10.0]
distribution: [0.0, 0.2, 0.7, 0.01]
normalize: False
```
:::{versionadded} 2.6
:::
(sec-yaml-pure-fluid)=
### `pure-fluid`
A phase representing a pure fluid equation of state for one of several pure substances
including liquid, vapor, two-phase, and supercritical regions, as
{ct}`described here <PureFluidPhase>`.
Additional fields:
`pure-fluid-name`
: Name of the pure fluid model to use:
- `carbon-dioxide`
- `heptane`
- `HFC-134a`
- `hydrogen`
- `methane`
- `nitrogen`
- `oxygen`
- `water`
Example:
```yaml
- name: carbon-dioxide
thermo: pure-fluid
species: [CO2]
state: {T: 280.0, P: 1.01325e+05}
pure-fluid-name: carbon-dioxide
```
(sec-yaml-redlich-kister)=
### `Redlich-Kister`
A phase employing the Redlich-Kister approximation for the excess Gibbs free energy, as
{ct}`described here <RedlichKisterVPSSTP>`.
Additional fields:
`interactions`
: A list of mappings, where each mapping has the following fields:
`species`
: A list of two species names
`excess-enthalpy`
: A list of polynomial coefficients for the excess enthalpy of the specified binary
interaction
`excess-entropy`
: A list of polynomial coefficients for the excess entropy of the specified binary
interaction
Example:
```yaml
- name: LiC6_and_Vacancies
thermo: Redlich-Kister
interactions:
- species: [Li(C6), V(C6)]
excess-enthalpy: [-3.268e+06, 3.955e+06, -4.573e+06, 6.147e+06, -3.339e+06,
1.117e+07, 2.997e+05, -4.866e+07, 1.362e+05, 1.373e+08,
-2.129e+07, -1.722e+08, 3.956e+07, 9.302e+07, -3.280e+07]
excess-entropy: [0.0]
```
(sec-yaml-redlich-kwong)=
### `Redlich-Kwong`
A multi-species Redlich-Kwong phase as {ct}`described here <RedlichKwongMFTP>`.
The parameters for each species are contained in the corresponding species
entries. See [Redlich-Kwong species equation of state](sec-yaml-eos-redlich-kwong).

934
doc/sphinx/yaml/phases.rst
View File

@ -1,934 +0,0 @@
.. highlight:: yaml
.. _sec-yaml-phases:
*****************
Phase Definitions
*****************
A ``phase`` is a mapping that contains definitions for the elements, species,
and optionally reactions that can take place in that phase. The fields of a
``phase`` entry are:
``name``
String identifier used for the phase. Required.
``elements``
Specification for the elements present in the phase. This can be:
- Omitted, in which case the standard elements will be added as needed by
the species included in the phase.
- A list of element symbols, which can be either defined in the ``elements``
section of the file or taken from the standard elements.
- A list of single-key mappings of section names to lists of element
symbols. These sections can be in the same file as the phase definition,
or from another file if written as ``file-path/sectionname``. If a
relative path is specified, the directory containing the current file is
searched first, followed by the Cantera data path. Standard elements can
be included by referencing the fictitious section ``default``.
.. _sec-yaml-phase-species:
``species``
Specification for the species present in the phase. This can be:
- a list of species that appear in the ``species`` section of the file.
- The string ``all``, to indicate that all species in the ``species``
section should be included. This is the default if no ``species`` entry
is present.
- A list of single-key mappings of section names to either the string
``all`` or a list of species names. These sections can be in the same
file as the phase definition, or from another file if written as
``file-path/sectionname``. If a relative path is specified, the directory
containing the current file is searched first, followed by the Cantera
data path.
Species may be skipped depending on the setting of the
``skip-undeclared-elements`` option.
``skip-undeclared-elements``
If set to ``true``, do not add species that contain elements that are not
explicitly included in the phase. The default is ``false``, where the
presence of such species is considered an error.
``skip-undeclared-third-bodies``
If set to ``true``, ignore third body efficiencies for species that are not
defined in the phase. The default is ``false``, where the presence of
such third body specifications is considered an error.
.. _sec-yaml-phase-explicit-third-body-duplicates:
``explicit-third-body-duplicates``
Specifies how to handle three body reactions with an explicit collider that are
duplicates of a three body reaction with the default collider ``M``. This can be:
- ``warn``: Issue a warning about such reactions. This is the default.
- ``error``: Raise an exception if such reactions are found.
- ``mark-duplicate``: Mark the reactions as duplicates. Species production and
consumption rates will reflect the sum of the rates. This option may correspond to
the behavior of software packages that do not check for this kind of duplicate
reaction.
- ``modify-efficiency``: Set the efficiency of the explicit third body to zero for the
reaction that gives the rate for the default collider. This option is the most
self-consistent but may not correspond to the intent of the mechanism's authors.
.. versionadded:: 3.1
``state``
A mapping specifying the thermodynamic state. See
:ref:`sec-yaml-setting-state`.
``adjacent-phases``
For interface phases, specification of adjacent phases that participate in reactions
on the interface. This can be:
- a list of phase names that appear in the ``phases`` section of the file.
- A list of single-key mappings of section names to a list of phase names. These
sections can be in the same file as the current phase definition, or from another
file if written as ``file-path/section-name``. If a relative path is specified,
the directory containing the current file is searched first, followed by the
Cantera data path.
.. _sec-yaml-phase-thermo:
``thermo``
String specifying the phase thermodynamic model to be used. Supported model
strings are:
- ``binary-solution-tabulated`` (:ref:`details <sec-yaml-binary-solution-tabulated>`)
- ``compound-lattice`` (:ref:`details <sec-yaml-compound-lattice>`)
- ``coverage-dependent-surface`` (:ref:`details <sec-yaml-coverage-dependent-surface>`)
- ``Debye-Huckel`` (:ref:`details <sec-yaml-Debye-Huckel>`)
- ``edge`` (:ref:`details <sec-yaml-edge>`)
- ``electron-cloud`` (:ref:`details <sec-yaml-electron-cloud>`)
- ``fixed-stoichiometry`` (:ref:`details <sec-yaml-fixed-stoichiometry>`)
- ``HMW-electrolyte`` (:ref:`details <sec-yaml-HMW-electrolyte>`)
- ``ideal-gas`` (:ref:`details <sec-yaml-ideal-gas>`)
- ``ideal-molal-solution`` (:ref:`details <sec-yaml-ideal-molal-solution>`)
- ``ideal-condensed`` (:ref:`details <sec-yaml-ideal-condensed>`)
- ``ideal-solution-VPSS`` (:ref:`details <sec-yaml-ideal-solution-VPSS>`)
- ``ideal-surface`` (:ref:`details <sec-yaml-ideal-surface>`)
- ``lattice`` (:ref:`details <sec-yaml-lattice>`)
- ``liquid-water-IAPWS95`` (:ref:`details <sec-yaml-liquid-water-IAPWS95>`)
- ``Margules`` (:ref:`details <sec-yaml-Margules>`)
- ``Peng-Robinson`` (:ref:`details <sec-yaml-Peng-Robinson>`)
- ``plasma`` (:ref:`details <sec-yaml-plasma>`)
- ``pure-fluid`` (:ref:`details <sec-yaml-pure-fluid>`)
- ``Redlich-Kister`` (:ref:`details <sec-yaml-Redlich-Kister>`)
- ``Redlich-Kwong`` (:ref:`details <sec-yaml-Redlich-Kwong>`)
.. _sec-yaml-phase-kinetics:
``kinetics``
String specifying the kinetics model to be used. Supported model strings
are:
- ``none``
- ``bulk`` (:ct:`details <BulkKinetics>`)
- ``gas`` (alias for ``bulk``)
- ``surface`` (:ct:`details <InterfaceKinetics>`)
- ``edge`` (:ct:`details <EdgeKinetics>`)
``reactions``
Source of reactions to include in the phase, if a kinetics model has been
specified. This can be:
- The string ``all``, which indicates that all reactions from the
``reactions`` section of the file should be included. This is the default
if no ``reactions`` entry is present.
- The string ``declared-species``, which indicates that all reactions from
the ``reactions`` section involving only species present in the phase
should be included.
- The string ``none``, which indicates that no reactions should be added.
This can be used if reactions will be added programmatically after
the phase is constructed.
- A list of sections from which to include reactions. These sections can be
in the same file as the phase definition, or from another file if written
as ``file-path/sectionname``. If a relative path is specified, the
directory containing the current file is searched first, followed by the
Cantera data path.
- A list of single-key mappings of section names to rules for adding
reactions, where for each section name, that rule is either ``all`` or
``declared-species`` and is applied as described above.
``Motz-Wise``
Boolean indicating whether the Motz-Wise correction should be applied to
sticking reactions. Applicable only to interface phases. The default is
``false``. The value set at the phase level may be overridden on individual
reactions.
.. _sec-yaml-phase-transport:
``transport``
String specifying the transport model to be used. Supported model strings
are:
- ``none``
- ``high-pressure``: A model for high-pressure gas transport properties based on a
method of corresponding states (:ct:`details <HighPressureGasTransport>`)
- ``ionized-gas``: A model implementing the Stockmayer-(n,6,4) model for transport
of ions in a gas (:ct:`details <IonGasTransport>`)
- ``mixture-averaged``: The mixture-averaged transport model for ideal gases
(:ct:`details <MixTransport>`)
- ``mixture-averaged-CK``: The mixture-averaged transport model for ideal gases,
using polynomial fits corresponding to Chemkin-II (:ct:`details <MixTransport>`)
- ``multicomponent``: The multicomponent transport model for ideal gases
(:ct:`details <MultiTransport>`)
- ``multicomponent-CK``: The multicomponent transport model for ideal gases, using
polynomial fits corresponding to Chemkin-II (:ct:`details <MultiTransport>`)
- ``unity-Lewis-number``: A transport model for ideal gases, where diffusion
coefficients for all species are set so that the Lewis number is 1
(:ct:`details <UnityLewisTransport>`)
- ``water``: A transport model for pure water applicable in both liquid and vapor
phases (:ct:`details <WaterTransport>`)
.. _sec-yaml-setting-state:
Setting the state
=================
The state of a ``phase`` can be set using two properties to set the
thermodynamic state, plus the composition.
The composition can be set using one of the following fields, depending on the
phase type. The composition is specified as a mapping of species names to
values. Where necessary, the values will be automatically normalized.
- ``mass-fractions`` or ``Y``
- ``mole-fractions`` or ``X``
- ``coverages``
- ``molalities`` or ``M``
The thermodynamic state can be set using the following property pairs, with some
exceptions for phases where setting that property pair is not implemented. All
properties are on a per unit mass basis where relevant:
- ``T`` and ``P``
- ``T`` and ``D``
- ``T`` and ``V``
- ``H`` and ``P``
- ``U`` and ``V``
- ``S`` and ``V``
- ``S`` and ``P``
- ``S`` and ``T``
- ``P`` and ``V``
- ``U`` and ``P``
- ``V`` and ``H``
- ``T`` and ``H``
- ``S`` and ``H``
- ``D`` and ``P``
The following synonyms are also implemented for use in any of the pairs:
- ``temperature``, ``T``
- ``pressure``, ``P``
- ``enthalpy``, ``H``
- ``entropy``, ``S``
- ``int-energy``, ``internal-energy``, ``U``
- ``specific-volume``, ``V``
- ``density``, ``D``
.. _sec-yaml-phase-thermo-models:
Phase thermodynamic models
==========================
.. _sec-yaml-binary-solution-tabulated:
``binary-solution-tabulated``
-----------------------------
A phase representing a binary solution where the excess enthalpy and entropy are
interpolated between tabulated values as a function of mole fraction, as
:ct:`described here <BinarySolutionTabulatedThermo>`.
Includes the fields of :ref:`sec-yaml-ideal-condensed`, plus:
``tabulated-species``
The name of the species to which the tabulated enthalpy and entropy is
added.
``tabulated-thermo``
A mapping containing three (optionally four) lists of equal lengths:
``mole-fractions``
A list of mole fraction values for the tabulated species.
``enthalpy``
The extra molar enthalpy to be added to the tabulated species at these
mole fractions.
``entropy``
The extra molar entropy to be added to the tabulated species at these
mole fractions.
``molar-volume``
The molar volume of the phase at these mole fractions. This input is
optional.
.. versionadded:: 2.5
.. _sec-yaml-compound-lattice:
``compound-lattice``
--------------------
A phase that is comprised of a fixed additive combination of other lattice
phases, as :ct:`described here <LatticeSolidPhase>`.
Additional fields:
``composition``
A mapping of component phase names to their relative stoichiometries.
Example::
thermo: compound-lattice
composition: {Li7Si3(s): 1.0, Li7Si3-interstitial: 1.0}
.. _sec-yaml-coverage-dependent-surface:
``coverage-dependent-surface``
------------------------------
A coverage-dependent surface phase. That is, a surface phase where the enthalpy,
entropy, and heat capacity of each species may depend on its coverage and the
coverage of other species in the phase.
Full details are :ct:`described here <CoverageDependentSurfPhase>`.
The majority of coverage dependency parameters are provided in the species entry as
:ref:`described here <sec-yaml-species-coverage>`.
Additional fields:
``site-density``
The molar density of surface sites.
``reference-state-coverage``
The reference state coverage denoting the low-coverage limit (ideal-surface)
thermodynamic properties.
Example::
- name: covdep
thermo: coverage-dependent-surface
species: [Pt, OC_Pt, CO2_Pt, C_Pt, O_Pt]
state:
T: 500.0
P: 1.01325e+05
coverages: {Pt: 0.5, OC_Pt: 0.5, CO2_Pt: 0.0, C_Pt: 0.0, O_Pt: 0.0}
site-density: 2.72e-09
reference-state-coverage: 0.22
.. versionadded:: 3.0
.. _sec-yaml-Debye-Huckel:
``Debye-Huckel``
----------------
A dilute liquid electrolyte which obeys the Debye-Hückel formulation for nonideality as
:ct:`described here <DebyeHuckel>`. Additional parameters for this model are contained
in the ``activity-data`` field:
``activity-data``
The activity data field contains the following fields:
``model``
One of ``dilute-limit``, ``B-dot-with-variable-a``,
``B-dot-with-common-a``, ``beta_ij``, or ``Pitzer-with-beta_ij``
``A_Debye``
The value of the Debye "A" parameter, or the string ``variable`` to use
a calculation based on the water equation of state. Defaults to the constant
value of 1.172576 kg^0.5/gmol^0.5, a nominal value for water at 298 K and 1 atm.
``B_Debye``
The Debye "B" parameter. Defaults to 3.2864e+09 kg^0.5/gmol^0.5/m, a nominal
value for water.
``max-ionic-strength``
The maximum ionic strength
``use-Helgeson-fixed-form``
Boolean, ``true`` or ``false``
``default-ionic-radius``
Ionic radius to use for species where the ionic radius has not been
specified.
``B-dot``
The value of B-dot.
``beta``
List of mappings providing values of :math:`\beta_{ij}` for different
species pairs. Each mapping contains a ``species`` key that contains a
list of two species names, and a ``beta`` key that contains the
corresponding value of :math:`\beta_{ij}`.
Example::
thermo: Debye-Huckel
activity-data:
model: beta_ij
max-ionic-strength: 3.0
use-Helgeson-fixed-form: true
default-ionic-radius: 3.042843 angstrom
beta:
- species: [H+, Cl-]
beta: 0.27
- species: [Na+, Cl-]
beta: 0.15
- species: [Na+, OH-]
beta: 0.06
In addition, the Debye-Hückel model uses several species-specific properties
which may be defined in the ``Debye-Huckel`` field of the *species* entry. These
properties are:
``ionic-radius``
Size of the species.
``electrolyte-species-type``
One of ``solvent``, ``charged-species``, ``weak-acid-associated``,
``strong-acid-associated``, ``polar-neutral``, or ``nonpolar-neutral``.
The type ``solvent`` is the default for the first species in the phase. The
type ``charged-species`` is the default for species with a net charge.
Otherwise, the default is and ``nonpolar-neutral``.
``weak-acid-charge``
Charge to use for species that can break apart into charged species.
Example::
name: NaCl(aq)
composition: {Na: 1, Cl: 1}
thermo:
model: piecewise-Gibbs
h0: -96.03E3 cal/mol
dimensionless: true
data: {298.15: -174.5057463, 333.15: -174.5057463}
equation-of-state:
model: constant-volume
molar-volume: 1.3
Debye-Huckel:
ionic-radius: 4 angstrom
electrolyte-species-type: weak-acid-associated
weak-acid-charge: -1.0
.. _sec-yaml-edge:
``edge``
--------
A one-dimensional edge between two surfaces, as :ct:`described here <EdgePhase>`.
Additional fields:
``site-density``
The molar density of sites per unit length along the edge
Example::
thermo: edge
site-density: 5.0e-17 mol/cm
.. _sec-yaml-electron-cloud:
``electron-cloud``
------------------
A phase representing an electron cloud, such as conduction electrons in a metal,
as :ct:`described here <MetalPhase>`.
Additional fields:
``density``
The density of the bulk metal
.. _sec-yaml-fixed-stoichiometry:
``fixed-stoichiometry``
-----------------------
An incompressible phase with fixed composition, as :ct:`described here <StoichSubstance>`.
.. _sec-yaml-HMW-electrolyte:
``HMW-electrolyte``
-------------------
A dilute or concentrated liquid electrolyte phase that obeys the Pitzer
formulation for nonideality, as :ct:`described here <HMWSoln>`.
Additional parameters for this model are contained in the ``activity-data``
field:
``activity-data``
The activity data field contains the following fields:
``temperature-model``
The form of the Pitzer temperature model. One of ``constant``,
``linear`` or ``complex``. The default is ``constant``.
``A_Debye``
The value of the Debye "A" parameter, or the string ``variable`` to use
a calculation based on the water equation of state. The default is
1.172576 kg^0.5/gmol^0.5, a nominal value for water at 298 K and 1 atm.
``max-ionic-strength``
The maximum ionic strength
``interactions``
A list of mappings, where each mapping describes a binary or ternary
interaction among species. Fields of this mapping include:
``species``
A list of one to three species names
``beta0``
The :math:`\beta^{(0)}` parameters for an cation/anion interaction.
1, 2, or 5 values depending on the value of ``temperature-model``.
``beta1``
The :math:`\beta^{(1)}` parameters for an cation/anion interaction.
1, 2, or 5 values depending on the value of ``temperature-model``.
``beta2``
The :math:`\beta^{(2)}` parameters for an cation/anion interaction.
1, 2, or 5 values depending on the value of ``temperature-model``.
``Cphi``
The :math:`C^\phi` parameters for an cation/anion interaction.
1, 2, or 5 values depending on the value of ``temperature-model``.
``alpha1``
The :math:`\alpha^{(1)}` parameter for an cation/anion interaction.
``alpha2``
The :math:`\alpha^{(2)}` parameter for an cation/anion interaction.
``theta``
The :math:`\theta` parameters for a like-charged binary interaction.
1, 2, or 5 values depending on the value of ``temperature-model``.
``lambda``
The :math:`\lambda` parameters for binary interactions involving at
least one neutral species. 1, 2, or 5 values depending on the value
of ``temperature-model``.
``psi``
The :math:`\Psi` parameters for ternary interactions involving three
charged species. 1, 2, or 5 values depending on the value of
``temperature-model``.
``zeta``
The :math:`\zeta` parameters for ternary interactions involving one
neutral species. 1, 2, or 5 values depending on the value of
``temperature-model``.
``mu``
The :math:`\mu` parameters for a neutral species self-interaction.
1, 2, or 5 values depending on the value of ``temperature-model``.
``cropping-coefficients``
``ln_gamma_k_min``
Default -5.0.
``ln_gamma_k_max``
Default 15.0.
``ln_gamma_o_min``
Default -6.0.
``ln_gamma_o_max``
Default 3.0.
Example::
thermo: HMW-electrolyte
activity-data:
temperature-model: complex
A_Debye: 1.175930 kg^0.5/gmol^0.5
interactions:
- species: [Na+, Cl-]
beta0: [0.0765, 0.008946, -3.3158E-6, -777.03, -4.4706]
beta1: [0.2664, 6.1608E-5, 1.0715E-6, 0.0, 0.0]
beta2: [0.0, 0.0, 0.0, 0.0, 0.0]
Cphi: [0.00127, -4.655E-5, 0.0, 33.317, 0.09421]
alpha1: 2.0
- species: [H+, Cl-]
beta0: [0.1775]
beta1: [0.2945]
beta2: [0.0]
Cphi: [0.0008]
alpha1: 2.0
- species: [Na+, OH-]
beta0: 0.0864
beta1: 0.253
beta2: 0.0
Cphi: 0.0044
alpha1: 2.0
alpha2: 0.0
- {species: [Cl-, OH-], theta: -0.05}
- {species: [Na+, Cl-, OH-], psi: -0.006}
- {species: [Na+, H+], theta: 0.036}
- {species: [Cl-, Na+, H+], psi: [-0.004]}
.. _sec-yaml-ideal-gas:
``ideal-gas``
-------------
A mixture which obeys the ideal gas law, as :ct:`described here <IdealGasPhase>`.
Example::
- name: ohmech
thermo: ideal-gas
elements: [O, H, Ar, N]
species: [H2, H, O, O2, OH, H2O, HO2, H2O2, AR, N2]
kinetics: gas
transport: mixture-averaged
state: {T: 300.0, P: 1 atm}
.. _sec-yaml-ideal-molal-solution:
``ideal-molal-solution``
------------------------
An ideal solution based on the mixing-rule assumption that all molality-based activity
coefficients are equal to one, as :ct:`described here <IdealMolalSoln>`.
Additional fields:
``standard-concentration-basis``
A string specifying the basis for the standard concentration. One of
``unity``, ``species-molar-volume``, or ``solvent-molar-volume``.
``cutoff``
Parameters for cutoff treatments of activity coefficients
``model``
``poly`` or ``polyExp``
``gamma_o``
gamma_o value for the cutoff process at the zero solvent point
``gamma_k``
gamma_k minimum for the cutoff process at the zero solvent point
``X_o``
value of the solute mole fraction that centers the cutoff polynomials
for the cutoff = 1 process
``c_0``
Parameter in the polyExp cutoff treatment having to do with rate of
exponential decay
``slope_f``
Parameter in the ``polyExp`` cutoff treatment
``slope_g``
Parameter in the ``polyExp`` cutoff treatment
Example::
thermo: ideal-molal-solution
standard-concentration-basis: solvent-molar-volume
cutoff:
model: polyexp
gamma_o: 0.0001
gamma_k: 10.0
X_o: 0.2
c_0: 0.05
slope_f: 0.6
slope_g: 0.0
.. _sec-yaml-ideal-condensed:
``ideal-condensed``
-------------------
An ideal liquid or solid solution as :ct:`described here <IdealSolidSolnPhase>`.
Additional fields:
``standard-concentration-basis``
A string specifying the basis for the standard concentration. One of
``unity``, ``species-molar-volume``, or ``solvent-molar-volume``.
.. _sec-yaml-ideal-solution-VPSS:
``ideal-solution-VPSS``
-----------------------
An ideal solution model using variable pressure standard state methods as
:ct:`described here <IdealSolnGasVPSS>`.
Additional fields:
``standard-concentration-basis``
A string specifying the basis for the standard concentration. One of
``unity``, ``species-molar-volume``, or ``solvent-molar-volume``.
.. _sec-yaml-ideal-surface:
``ideal-surface``
-----------------
An ideal surface between two bulk phases, as :ct:`described here <SurfPhase>`.
Additional fields:
``site-density``
The molar density of surface sites
Example::
- name: Pt_surf
thermo: ideal-surface
adjacent-phases: [gas]
elements: [Pt, H, O, C]
species: [PT(S), H(S), H2O(S), OH(S), CO(S), CO2(S), CH3(S), CH2(S)s,
CH(S), C(S), O(S)]
kinetics: surface
reactions: all
state:
T: 900.0
coverages: {O(S): 0.0, PT(S): 0.5, H(S): 0.5}
site-density: 2.7063e-09
.. _sec-yaml-lattice:
``lattice``
-----------
A simple thermodynamic model for a bulk phase, assuming an incompressible lattice of
solid atoms, as :ct:`described here <LatticePhase>`.
Additional fields:
``site-density``
The molar density of lattice sites
.. _sec-yaml-liquid-water-IAPWS95:
``liquid-water-IAPWS95``
------------------------
An implementation of the IAPWS95 equation of state for water :cite:p:`wagner2002`, for
the liquid region only as :ct:`described here <WaterSSTP>`.
.. _sec-yaml-Margules:
``Margules``
------------
A phase employing the Margules approximation for the excess Gibbs free energy, as
:ct:`described here <MargulesVPSSTP>`.
Additional fields:
``interactions``
A list of mappings, where each mapping has the following fields:
``species``
A list of two species names
``excess-enthalpy``
A list of two values specifying the first and second excess enthalpy
coefficients for the interaction of the specified species. Defaults to
[0, 0].
``excess-entropy``
A list of two values specifying the first and second excess entropy
coefficients for the interaction of the specified species. Defaults to
[0, 0].
``excess-volume-enthalpy``
A list of two values specifying the first and second enthalpy
coefficients for the excess volume interaction of the specified species.
Defaults to [0, 0].
``excess-volume-entropy``
A list of two values specifying the first and second entropy
coefficients for the excess volume interaction of the specified species.
Defaults to [0, 0].
Example::
thermo: Margules
interactions:
- species: [KCl(l), LiCl(l)]
excess-enthalpy: [-17570, -377]
excess-entropy: [-7.627, 4.958]
.. _sec-yaml-Peng-Robinson:
``Peng-Robinson``
-----------------
A multi-species real gas following the Peng-Robinson equation of state, as
:ct:`described here <PengRobinson>`.
The parameters for each species are contained in the corresponding species
entries. See :ref:`Peng-Robinson species equation of state <sec-yaml-eos-peng-robinson>`.
.. versionadded:: 3.0
.. _sec-yaml-plasma:
``plasma``
----------
A phase for plasma. This phase handles plasma properties such as the electron
energy distribution and electron temperature with different models as
:ct:`described here <PlasmaPhase>`.
Additional fields:
``electron-energy-distribution``
A mapping with the following fields:
``type``
String specifying the type of the electron energy distribution to be used.
Supported model strings are:
- `isotropic`
- `discretized`
``shape-factor``
A constant in the isotropic distribution, which is shown as x in the
detailed description of this class. The value needs to be a positive
number. This field is only used with `isotropic`. Defaults to 2.0.
``mean-electron-energy``
Mean electron energy of the isotropic distribution. The default sets
the electron temperature equal gas temperature and uses the
corresponding electron energy as mean electron energy. This field
is only used with `isotropic`.
``energy-levels``
A list of values specifying the electron energy levels. The default
uses 1001 equal spaced points from 0 to 1 eV.
``distribution``
A list of values specifying the discretized electron energy distribution.
This field is only used with `discretized`.
``normalize``
A flag specifying whether normalizing the discretized electron energy
distribution or not. This field is only used with `discretized`.
Defaults to ``true``.
Example::
- name: isotropic-electron-energy-plasma
thermo: plasma
kinetics: gas
transport: ionized-gas
electron-energy-distribution:
type: isotropic
shape-factor: 2.0
mean-electron-energy: 1.0 eV
energy-levels: [0.0, 0.1, 1.0, 10.0]
- name: discretized-electron-energy-plasma
thermo: plasma
kinetics: gas
transport: ionized-gas
electron-energy-distribution:
type: discretized
energy-levels: [0.0, 0.1, 1.0, 10.0]
distribution: [0.0, 0.2, 0.7, 0.01]
normalize: False
.. versionadded:: 2.6
.. _sec-yaml-pure-fluid:
``pure-fluid``
--------------
A phase representing a pure fluid equation of state for one of several pure substances
including liquid, vapor, two-phase, and supercritical regions, as
:ct:`described here <PureFluidPhase>`.
Additional fields:
``pure-fluid-name``
Name of the pure fluid model to use:
- ``carbon-dioxide``
- ``heptane``
- ``HFC-134a``
- ``hydrogen``
- ``methane``
- ``nitrogen``
- ``oxygen``
- ``water``
.. _sec-yaml-Redlich-Kister:
``Redlich-Kister``
------------------
A phase employing the Redlich-Kister approximation for the excess Gibbs free
energy, as :ct:`described here <RedlichKisterVPSSTP>`.
Additional fields:
``interactions``
A list of mappings, where each mapping has the following fields:
``species``
A list of two species names
``excess-enthalpy``
A list of polynomial coefficients for the excess enthalpy of the
specified binary interaction
``excess-entropy``
A list of polynomial coefficients for the excess entropy of the
specified binary interaction
Example::
thermo: Redlich-Kister
interactions:
- species: [Li(C6), V(C6)]
excess-enthalpy: [-3.268e+06, 3.955e+06, -4.573e+06, 6.147e+06, -3.339e+06,
1.117e+07, 2.997e+05, -4.866e+07, 1.362e+05, 1.373e+08,
-2.129e+07, -1.722e+08, 3.956e+07, 9.302e+07, -3.280e+07]
excess-entropy: [0.0]
.. _sec-yaml-Redlich-Kwong:
``Redlich-Kwong``
-----------------
A multi-species Redlich-Kwong phase as :ct:`described here <RedlichKwongMFTP>`.
The parameters for each species are contained in the corresponding species
entries. See :ref:`Redlich-Kwong species equation of state <sec-yaml-eos-redlich-kwong>`.

706
doc/sphinx/yaml/reactions.md Normal file
View File

@ -0,0 +1,706 @@
(sec-yaml-reactions)=
# Reactions
The fields common to all `reaction` entries are:
`equation`
: The stoichiometric equation for the reaction. Each term (that is, stoichiometric
coefficient, species name, `+` or `<=>`) in the equation must be separated by a space.
Reversible reactions may be written using `<=>` or `=` to separate reactants and
products. Irreversible reactions are written using `=>`.
`type`
: A string specifying the type of reaction or rate coefficient parameterization. The
default is `elementary`. Reaction types are:
- [`elementary`](sec-yaml-elementary)
- [`three-body`](sec-yaml-three-body)
- [`Blowers-Masel`](sec-yaml-Blowers-Masel)
- [`two-temperature-plasma`](sec-yaml-two-temperature-plasma)
- [`electron-collision-plasma`](sec-yaml-electron-collision-plasma)
- [`falloff`](sec-yaml-falloff)
- [`chemically-activated`](sec-yaml-chemically-activated)
- [`pressure-dependent-Arrhenius`](sec-yaml-pressure-dependent-Arrhenius)
- [`Chebyshev`](sec-yaml-Chebyshev)
- [`linear-Burke`](sec-yaml-linear-Burke)
Reactions without a specified `type` on surfaces or edges are automatically treated as
[`interface-Arrhenius`](sec-yaml-interface-Arrhenius) reactions, unless a
`sticking-coefficient` implies a [`sticking-Arrhenius`](sec-yaml-sticking-Arrhenius)
reaction. Interface reactions that involve charge transfer between phases are
automatically treated as [`electrochemical`](sec-yaml-electrochemical-reaction)
reactions.
Reactions on surfaces or edges specifying `type` as `Blowers-Masel` are treated as
[`interface-Blowers-Masel`](sec-yaml-interface-Blowers-Masel) or
[`sticking-Blowers-Masel`](sec-yaml-sticking-Blowers-Masel).
`duplicate`
: Boolean indicating whether the reaction is a known duplicate of another reaction. The
default is `false`.
`orders`
: An optional mapping of species to explicit reaction orders to use. Reaction orders for
reactant species not explicitly mentioned are taken to be their respective
stoichiometric coefficients. See [](sec-reaction-orders) for additional information.
`negative-orders`
: Boolean indicating whether negative reaction orders are allowed. The default is
`false`.
`nonreactant-orders`
: Boolean indicating whether orders for non-reactant species are allowed. The default is
`false`.
Depending on the reaction `type`, other fields may be necessary to specify the rate of
the reaction.
## Reaction rate expressions
(sec-yaml-arrhenius-rate)=
### Arrhenius
Arrhenius rate expressions are specified as a mapping with fields:
`A`
: The pre-exponential factor $A$
`b`
: The temperature exponent $b$
`Ea`
: The activation energy $E_a$
or a corresponding three-element list. The following are equivalent:
```yaml
{A: 2.70E+13 cm^3/mol/s, b: 0, Ea: 355 cal/mol}
[2.70E+13 cm^3/mol/s, 0, 355 cal/mol]
```
(sec-yaml-blowers-masel-rate)=
### Blowers-Masel
Blowers-Masel rate expressions calculate the rate constant based on the Blowers Masel
approximation as [described here](sec-blowers-masel). The rate parameters are specified
as a mapping with fields:
`A`
: The pre-exponential factor $A$
`b`
: The temperature exponent $b$
`Ea0`
: The intrinsic activation energy $E_{a0}$
`w`
: The average of the bond dissociation energy of the bond breaking and that being formed
in the reaction $w$
or a corresponding four-element list. The following are equivalent:
```yaml
{A: 3.87e+04 cm^3/mol/s, b: 2.7, Ea0: 6260.0 cal/mol, w: 1e9 cal/mol}
[3.87e+04 cm^3/mol/s, 2.7, 6260.0 cal/mol, 1e9 cal/mol]
```
(sec-yaml-two-temperature-plasma-rate)=
### Two-Temperature Plasma
Two-temperature plasma reactions involve an electron as one of the reactants, where the
electron temperature may differ from the gas temperature as
[described here](sec-two-temperature-plasma-rate). The rate parameters are specified as
a mapping with fields:
`A`
: The pre-exponential factor
`b`
: The temperature exponent, which is applied to the electron temperature
`Ea-gas`
: The activation energy term $E_{a,g}$ that is related to the gas temperature
`Ea-electron`
: The activation energy term $E_{a,e}$ that is related to the electron temperature
or a corresponding four-element list. The following are equivalent:
```yaml
{A: 17283, b: -3.1, Ea-gas: -5820 J/mol, Ea-electron: 1081 J/mol}
[17283, -3.1, -5820 J/mol, 1081 J/mol]
```
(sec-yaml-efficiencies)=
## Efficiencies
Some reaction types include parameters for the "efficiency" of different species as
third-body colliders. For these reactions, the following additional fields are
supported:
`efficiencies`
: A mapping of species names to efficiency values
`default-efficiency`
: The efficiency for use for species not included in the `efficiencies` mapping.
Defaults to 1.0.
Examples:
```yaml
- equation: O + H + M <=> OH + M
rate-constant: {A: 5.0e+5, b: -1.0, Ea: 0.0}
default-efficiency: 0.0
efficiencies: {H2: 2.0, H2O: 6.0, AR: 0.7}
- equation: O + H + M <=> OH + M
rate-constant: {A: 3.0e+5, b: 0.0, Ea: 123.0}
# Efficiencies for the species in the previous reaction must be explicitly zero
# to avoid double counting and being considered a duplicate reaction
efficiencies: {H2: 0.0, H2O: 0.0, AR: 0.0, CO: 3.0}
```
(sec-yaml-rate-types)=
## Reaction types
(sec-yaml-elementary)=
### `elementary`
A homogeneous reaction with a pressure-independent rate coefficient and mass action
kinetics, as [described here](sec-arrhenius-rate).
Additional fields are:
`rate-constant`
: An [Arrhenius-type](sec-yaml-Arrhenius-rate) list or mapping.
`negative-A`
: A boolean indicating whether a negative value for the pre-exponential factor is
allowed. The default is `false`.
Example:
```yaml
- equation: N + NO <=> N2 + O
rate-constant: {A: -2.70000E+13 cm^3/mol/s, b: 0, Ea: 355 cal/mol}
negative-A: true
```
(sec-yaml-three-body)=
### `three-body`
A three body reaction as [described here](sec-three-body-reaction).
The reaction equation must include a third body collision partner, which may be either a
specific species or the generic third body `M`.
Includes the fields of an `elementary` reaction, plus the fields for specifying
[efficiencies](sec-yaml-efficiencies).
Example:
```yaml
- equation: 2 O + M = O2 + M
type: three-body
rate-constant: [1.20000E+17 cm^6/mol^2/s, -1, 0]
efficiencies: {AR: 0.83, H2O: 5}
```
The `type` field of the YAML entry may be omitted. Reactions containing the generic
third body M are automatically identified as three-body reactions. Reactions are also
identified as three-body reactions if all of the following conditions are met:
- There is exactly one species appearing as both a reactant and product
- All reactants and products have integral stoichiometric coefficients
- The sum of the stoichiometric coefficients for either the reactants or products is 3.
Examples:
```yaml
- equation: H + 2 O2 <=> HO2 + O2 # Reaction 34
rate-constant: {A: 2.08e+19, b: -1.24, Ea: 0.0}
- equation: H + O2 + N2 <=> HO2 + N2 # Reaction 36
rate-constant: {A: 2.6e+19, b: -1.24, Ea: 0.0}
```
````{caution}
If a corresponding reaction with the generic third body M also appears in the
mechanism, such as:
```yaml
- equation: H + O2 + M <=> HO2 + M # Reaction 33
rate-constant: {A: 2.8e+18, b: -0.86, Ea: 0.0}
efficiencies: {O2: 0.0, H2O: 0.0, CO: 0.75, CO2: 1.5, C2H6: 1.5, N2: 0.0, AR: 0.0}
```
then the third body efficiency for any third bodies that are given in the explicit
form of Reaction 34 or Reaction 35 above must be set to zero, as shown here for
O2 and N2, or the reactions must be marked as duplicate.
````
:::{versionchanged} 3.0
Three body reactions are detected automatically and the the `type` field may be omitted.
Reactions with explicit third bodies are required to be marked as duplicates of
reactions with the generic third body if the corresponding efficiency is not zero.
:::
:::{versionadded} 3.1
Reactions with explicit third bodies and the corresponding reaction with "M" issue
warnings instead of raising errors by default. The
[](sec-yaml-phase-explicit-third-body-duplicates) field of the phase entry can be used
to control how these reactions are handled.
:::
(sec-yaml-blowers-masel)=
### `Blowers-Masel`
Includes the fields of an [`elementary`](sec-yaml-elementary) reaction, except that the
`rate-constant` field is a [Blowers-Masel-type](sec-yaml-Blowers-Masel-rate) list or
mapping.
Example:
```yaml
- equation: O + H2 <=> H + OH
type: Blowers-Masel
rate-constant: {A: 3.87e+04 cm^2/mol/s, b: 2.7, Ea0: 6260.0 cal/mol, w: 1e9 cal/mol}
```
(sec-yaml-two-temperature-plasma)=
### `two-temperature-plasma`
Includes the fields of an [`elementary`](sec-yaml-elementary) reaction, except that the
`rate-constant` field is a
[`two-temperature-plasma`](sec-yaml-two-temperature-plasma-rate) list or mapping.
Example:
```yaml
- equation: O + H => O + H
type: two-temperature-plasma
rate-constant: {A: 17283, b: -3.1, Ea-gas: -5820 J/mol, Ea-electron: 1081 J/mol}
```
(sec-yaml-electron-collision-plasma)=
### `electron-collision-plasma`
Electron collision plasma reactions involve an electron as one of the reactants, and are
parameterized by the collision cross section as a function of the electron energy. The
rate calculation is [described here](sec-electron-collision-plasma-rate). The rate
parameters are specified using the following additional fields in the reaction entry:
`energy-levels`
: A list of electron energy levels [V]
`cross-sections`
: A list of collision cross sections [m²] for the reaction at the specified energy
levels.
Example:
```yaml
- equation: O2 + e => e + e + O2+
type: electron-collision-plasma
energy-levels: [13.0, 15.5, 18, 23]
cross-sections: [1.17e-22, 7.3e-22, 1.64e-21, 3.66e-21]
```
:::{versionadded} 3.1
:::
(sec-yaml-falloff)=
### `falloff`
A falloff reaction as [described here](sec-falloff-rate).
The reaction equation should include the pressure-dependent third body collision partner
`(+M)` or `(+name)` where `name` is the name of a species. The latter case is equivalent
to setting the efficiency for `name` to 1 and the efficiency for all other species to 0.
Includes field for specifying {ref}`efficiencies <sec-yaml-efficiencies>` as well as:
`high-P-rate-constant`
: An [](sec-yaml-Arrhenius-rate) expression for the high-pressure limit
`low-P-rate-constant`
: An [](sec-yaml-Arrhenius-rate) expression for the low-pressure limit
`Troe`
: Parameters for the [Troe](sec-troe-falloff) falloff function. A mapping containing the
keys `A`, `T3`, `T1` and optionally `T2`. The default value for `T2` is 0.
`SRI`
: Parameters for the [SRI](sec-sri-falloff) falloff function. A mapping containing the
keys `A`, `B`, `C`, and optionally `D` and `E`. The default values for `D` and `E` are
1.0 and 0.0, respectively.
`Tsang`
: Parameters for the [Tsang](sec-tsang-falloff) falloff function. A mapping containing
the keys `A` and `B`. The default value for `B` is 0.0.
Examples:
```yaml
- equation: H + CH2 (+ N2) <=> CH3 (+N2)
type: falloff
high-P-rate-constant: [6.00000E+14 cm^3/mol/s, 0, 0]
low-P-rate-constant: {A: 1.04000E+26 cm^6/mol^2/s, b: -2.76, Ea: 1600}
Troe: {A: 0.562, T3: 91, T1: 5836}
- equation: O + CO (+M) <=> CO2 (+M)
type: falloff # Lindemann form since no additional falloff function parameters given
low-P-rate-constant: {A: 6.02e+14, b: 0.0, Ea: 3000.0}
high-P-rate-constant: {A: 1.8e+10, b: 0.0, Ea: 2385.0}
efficiencies: {H2: 2.0, O2: 6.0, H2O: 6.0, CH4: 2.0, CO: 1.5, CO2: 3.5,
C2H6: 3.0, AR: 0.5}
```
(sec-yaml-chemically-activated)=
### `chemically-activated`
A chemically activated reaction as [described here](sec-chemically-activated-rate).
The parameters are the same as for {ref}`sec-yaml-falloff` reactions.
Example:
```yaml
- equation: CH3 + OH (+M) <=> CH2O + H2 (+M)
type: chemically-activated
high-P-rate-constant: [5.88E-14, 6.721, -3022.227]
low-P-rate-constant: [282320.078, 1.46878, -3270.56495]
```
(sec-yaml-pressure-dependent-arrhenius)=
### `pressure-dependent-Arrhenius`
A pressure-dependent reaction using multiple Arrhenius expressions as
[described here](sec-plog-rate).
The only additional field in this reaction type is:
`rate-constants`
: A list of mappings, where each mapping is the mapping form of an
[](sec-yaml-Arrhenius-rate) expression with the addition of a pressure `P`.
Example:
```yaml
- equation: H + CH4 <=> H2 + CH3
type: pressure-dependent-Arrhenius
rate-constants:
- {P: 0.039474 atm, A: 2.720000e+09 cm^3/mol/s, b: 1.2, Ea: 6834.0}
- {P: 1.0 atm, A: 1.260000e+20, b: -1.83, Ea: 15003.0}
- {P: 1.0 atm, A: 1.230000e+04, b: 2.68, Ea: 6335.0}
- {P: 1.01325 MPa, A: 1.680000e+16, b: -0.6, Ea: 14754.0}
```
(sec-yaml-chebyshev)=
### `Chebyshev`
A reaction parameterized as a bivariate Chebyshev polynomial as
[described here](sec-chebyshev-rate).
Additional fields are:
`temperature-range`
: A list of two values specifying the minimum and maximum temperatures at which the rate
constant is valid
`pressure-range`
: A list of two values specifying the minimum and maximum pressures at which the rate
constant is valid
`data`
: A list of lists containing the Chebyshev coefficients
Example:
```yaml
- equation: CH4 <=> CH3 + H
type: Chebyshev
temperature-range: [290, 3000]
pressure-range: [0.0098692326671601278 atm, 98.692326671601279 atm]
data: [[-1.44280e+01, 2.59970e-01, -2.24320e-02, -2.78700e-03],
[ 2.20630e+01, 4.88090e-01, -3.96430e-02, -5.48110e-03],
[-2.32940e-01, 4.01900e-01, -2.60730e-02, -5.04860e-03],
[-2.93660e-01, 2.85680e-01, -9.33730e-03, -4.01020e-03],
[-2.26210e-01, 1.69190e-01, 4.85810e-03, -2.38030e-03],
[-1.43220e-01, 7.71110e-02, 1.27080e-02, -6.41540e-04]]
```
(sec-yaml-linear-burke)=
### `linear-Burke`
A complex-forming reaction (one that depends on both P and X) parameterized according to
the reduced-pressure linear mixture rule as [described here](sec-linear-Burke).
`efficiency` and `eig0` comprise the two acceptable ways to represent the contribution
of each bath gas component (collider) to the reduced pressure. All explicitly defined
colliders must include either `efficiency` or `eig0`, but the choice must remain
consistent throughout a single reaction (either all colliders are defined with
`efficiency`, or all are defined with `eig0`).
The pressure-dependent aspect of each collider rate constant can be parameterized in the
user's choice of [`Troe`](sec-yaml-falloff),
[`pressure-dependent-Arrhenius`](sec-yaml-pressure-dependent-Arrhenius), or
[`Chebyshev`](sec-yaml-Chebyshev) representations. The same parameters used for a
standalone Troe, PLOG, or Chebyshev reaction are then inserted directly below
`efficiency` or `eig0` for a given collider. At minimum, this treatment must be applied
to `M`. However, additional colliders may also be given their own Troe, PLOG, or
Chebyshev parameterization if so desired. Mixing and matching of types within the same
reaction is allowed (e.g., a PLOG table for `M`, Troe parameters for `H2`, and Chebyshev
data for `NH3`).
A mathematical description of this YAML implementation can be found in Eq. 8 of
{cite:t}`singal2024`.
Additional fields are:
`colliders`
: A list of dictionaries, where each entry contains parameters corresponding to
individual colliders (species in the bath gas). Each entry within the `colliders` list
may contain the following fields:
`name`
: The name of the collider species (e.g., `H2O`). The first collider defined must be
`M`, which represents the generic reference collider (often `Ar` or `N2`) that
represents all species lacking their own explicit parameterization.
`eig0`
: The absolute value of the least negative chemically significant eigenvalue of the
master equation for the $i^{th}$ collider (when pure), evaluated at the low-pressure
limit, $\Lambda_{0,i}(T)[M]$. The user must explicitly assign an `eig0` for `M`.
This parameter is entered in modified Arrhenius format to enable consideration of
temperature dependence.
`efficiency`
: The third-body efficiency of the collider relative to that of the reference collider
`M`, defined as $\epsilon_{0,i}(T)=\Lambda_{0,i}(T)/\Lambda_{0,\text{M}}(T)$. The
user does not need to assign an `efficiency` for `M`, as it is always equal to 1 by
definition. However, they are free to do so, as long as it takes the form
`efficiency: {A: 1, b: 0, Ea: 0}` (no variations are permitted). This parameter is
entered in modified Arrhenius format to enable consideration of temperature
dependence. If the user wishes to specify a temperature-independent value, then `A`
can be set to this value and `b` and `Ea` can be set to 0 (such as
`H2O: {A: 10, b: 0, Ea: 0}`).
A [`Troe`](sec-yaml-falloff) implementation also requires: `high-P-rate-constant`,
`low-P-rate-constant`, `Troe` (do not use the Troe `efficiencies` key).
A [`pressure-dependent-Arrhenius`](sec-yaml-pressure-dependent-Arrhenius)
implementation also requires: `rate-constants`.
A [`Chebyshev`](sec-yaml-Chebyshev) implementation also requires: `temperature-range`,
`pressure-range`, `data`.
Examples:
`linear-Burke` *rate with Troe format for the reference collider (N2)*:
```yaml
- equation: H + OH <=> H2O
type: linear-Burke
colliders:
- name: M
type: falloff
low-P-rate-constant: {A: 4.530000e+21, b: -1.820309e+00, Ea: 4.987000e+02}
high-P-rate-constant: {A: 2.510000e+13, b: 2.329303e-01, Ea: -1.142000e+02}
Troe: {A: 9.995044e-01, T3: 1.0e-30, T1: 1.0e+30}
- name: AR
efficiency: {A: 2.20621e-02, b: 4.74036e-01, Ea: -1.13148e+02}
- name: H2O
efficiency: {A: 1.04529e-01, b: 5.50787e-01, Ea: -2.32675e+02}
```
`linear-Burke` *rate with PLOG format for the reference collider (Ar)*:
```yaml
- equation: H + O2 (+M) <=> HO2 (+M) # Adding '(+M)' is optional
type: linear-Burke
colliders:
- name: M
type: pressure-dependent-Arrhenius
rate-constants:
- {P: 1.316e-02 atm, A: 9.39968e+14, b: -2.14348e+00, Ea: 7.72730e+01}
- {P: 1.316e-01 atm, A: 1.07254e+16, b: -2.15999e+00, Ea: 1.30239e+02}
- {P: 3.947e-01 atm, A: 3.17830e+16, b: -2.15813e+00, Ea: 1.66994e+02}
- {P: 1.000e+00 atm, A: 7.72584e+16, b: -2.15195e+00, Ea: 2.13473e+02}
- {P: 3.000e+00 atm, A: 2.11688e+17, b: -2.14062e+00, Ea: 2.79031e+02}
- {P: 1.000e+01 atm, A: 6.53093e+17, b: -2.13213e+00, Ea: 3.87493e+02}
- {P: 3.000e+01 atm, A: 1.49784e+18, b: -2.10026e+00, Ea: 4.87579e+02}
- {P: 1.000e+02 atm, A: 3.82218e+18, b: -2.07057e+00, Ea: 6.65984e+02}
- name: HE
efficiency: {A: 3.37601e-01, b: 1.82568e-01, Ea: 3.62408e+01}
- name: N2
efficiency: {A: 1.24932e+02, b: -5.93263e-01, Ea: 5.40921e+02}
- name: H2
efficiency: {A: 3.13717e+04, b: -1.25419e+00, Ea: 1.12924e+03}
- name: CO2
efficiency: {A: 1.62413e+08, b: -2.27622e+00, Ea: 1.97023e+03}
- name: NH3
efficiency: {A: 4.97750e+00, b: 1.64855e-01, Ea: -2.80351e+02}
- name: H2O
efficiency: {A: 3.69146e+01, b: -7.12902e-02, Ea: 3.19087e+01}
```
`linear-Burke` *rate with Chebyshev format for the reference collider (Ar)*:
```yaml
- equation: H2O2 <=> 2 OH
type: linear-Burke
colliders:
- name: M
type: Chebyshev
temperature-range: [200.0, 2000.0]
pressure-range: [1.000e-01 atm, 1.000e+02 atm]
data:
- [-1.58e+01, 8.71e-01, -9.44e-02, -2.81e-03, -4.48e-04, 1.58e-03, -2.51e-04]
- [2.32e+01, 5.27e-01, 2.89e-02, -5.46e-03, 7.08e-04, -3.03e-03, 7.81e-04]
- [-3.80e-01, 8.63e-02, 4.03e-02, -7.23e-03, 5.76e-04, 2.79e-03, -1.49e-03]
- [-1.48e-01, -7.18e-03, 2.21e-02, 6.23e-03, -5.98e-03, -8.22e-06, 1.92e-03]
- [-6.06e-02, -1.42e-02, 1.34e-03, 9.62e-03, 1.70e-03, -3.65e-03, -4.32e-04]
- [-2.46e-02, -9.71e-03, -5.88e-03, 3.05e-03, 5.87e-03, 1.50e-03, -2.01e-03]
- [-1.54e-02, -5.24e-03, -6.91e-03, -5.94e-03, -1.22e-03, 2.17e-03, 1.59e-03]
- name: N2
efficiency: {A: 1.14813e+00, b: 4.60090e-02, Ea: -2.92413e+00}
- name: CO2
efficiency: {A: 8.98839e+01, b: -4.27974e-01, Ea: 2.41392e+02}
- name: H2O2
efficiency: {A: 6.45295e-01, b: 4.26266e-01, Ea: 4.28932e+01}
- name: H2O
efficiency: {A: 1.36377e+00, b: 3.06592e-01, Ea: 2.10079e+02}
```
(sec-yaml-interface-arrhenius)=
### `interface-Arrhenius`
A reaction occurring on a surface between two bulk phases, or along an edge at the
intersection of two surfaces, as [described here](sec-surface-rate).
Includes the fields of an [](sec-yaml-elementary) reaction plus:
`coverage-dependencies`
: A mapping of species names to coverage dependence parameters, where these
parameters are contained in either a mapping with the fields:
`a`
: Coefficient for exponential dependence on the coverage
`m`
: Power-law exponent of coverage dependence
`E`
: Activation energy dependence on coverage, which uses the same sign convention as the
leading-order activation energy term. This can be a scalar value for the linear
dependency or a list of four values for the polynomial dependency given in the order
of 1st, 2nd, 3rd, and 4th-order coefficients
or a list containing the three elements above, in the given order.
Note that parameters `a`, `m` and `E` correspond to parameters $\eta_{ki}$, $\mu_{ki}$
and $\epsilon_{ki}$ in Eq 11.113 of {cite:t}`kee2003`, respectively.
Examples:
```yaml
- equation: 2 H(s) => H2 + 2 Pt(s)
rate-constant: {A: 3.7e21 cm^2/mol/s, b: 0, Ea: 67400 J/mol}
coverage-dependencies: {H(s): {a: 0, m: 0, E: -6000 J/mol}}
- equation: 2 O(S) => O2 + 2 Pt(S)
rate-constant: {A: 3.7e+21, b: 0, Ea: 213200 J/mol}
coverage-dependencies: {O(S): {a: 0.0, m: 0.0,
E: [1.0e3 J/mol, 3.0e3 J/mol , -7.0e4 J/mol , 5.0e3 J/mol]}}
- equation: CH4 + PT(S) + O(S) => CH3(S) + OH(S)
rate-constant: {A: 5.0e+18, b: 0.7, Ea: 4.2e+04}
coverage-dependencies:
O(S): [0, 0, 8000]
PT(S): [0, -1.0, 0]
- equation: 2 O(S) => O2 + 2 Pt(S)
rate-constant: {A: 3.7e+21, b: 0, Ea: 213200 J/mol}
coverage-dependencies:
O(S): [0, 0, [1.0e6, 3.0e6, -7.0e7, 5.0e6]]
```
(sec-yaml-interface-blowers-masel)=
### `interface-Blowers-Masel`
Includes the same fields as [`interface-Arrhenius`](sec-yaml-interface-Arrhenius), while
using the [Blowers-Masel](sec-yaml-Blowers-Masel-rate) parameterization for the rate
constant.
Example:
```yaml
- equation: 2 H(s) => H2 + 2 Pt(s)
type: Blowers-Masel
rate-constant: {A: 3.7e21 cm^2/mol/s, b: 0, Ea0: 67400 J/mol, w: 1000000 J/mol}
coverage-dependencies: {H(s): {a: 0, m: 0, E: -6000 J/mol}}
```
(sec-yaml-sticking-arrhenius)=
### `sticking-Arrhenius`
A sticking reaction occurring on a surface adjacent to a bulk phase, as
[described here](sec-sticking-rate).
Includes the fields of an [](sec-yaml-interface-Arrhenius) reaction plus:
`sticking-coefficient`
: An [Arrhenius-type](sec-yaml-Arrhenius-rate) expression for the sticking coefficient
`Motz-Wise`
: A boolean indicating whether to use the Motz-Wise correction factor for sticking
coefficients near unity. Defaults to `false`.
`sticking-species`
: The name of the sticking species. Required if the reaction includes multiple
non-surface species.
Example:
```yaml
- equation: OH + PT(S) => OH(S)
sticking-coefficient: {A: 1.0, b: 0, Ea: 0}
```
(sec-yaml-sticking-blowers-masel)=
### `sticking-Blowers-Masel`
Includes the same fields as [`sticking-Arrhenius`](sec-yaml-sticking-Arrhenius), while
using the [Blowers-Masel](sec-yaml-Blowers-Masel-rate) parameterization
for the sticking coefficient.
Example:
```yaml
- equation: OH + PT(S) => OH(S)
type: Blowers-Masel
sticking-coefficient: {A: 1.0, b: 0, Ea0: 0, w: 100000}
Motz-Wise: true
```
(sec-yaml-electrochemical-reaction)=
### `electrochemical`
Interface reactions involving [charge transfer](sec-electrochemical-reactions) between
phases.
Includes the fields of an [](sec-yaml-interface-Arrhenius) reaction, plus:
`beta`
: The symmetry factor for the reaction. Default is 0.5.
`exchange-current-density-formulation`
: Set to `true` if the rate constant parameterizes the exchange current density. Default
is `false`.
Example:
```yaml
- equation: LiC6 <=> Li+(e) + C6
rate-constant: [5.74, 0.0, 0.0]
beta: 0.4
```

678
doc/sphinx/yaml/reactions.rst
View File

@ -1,678 +0,0 @@
.. highlight:: yaml
.. _sec-yaml-reactions:
*********
Reactions
*********
The fields common to all ``reaction`` entries are:
``equation``
The stoichiometric equation for the reaction. Each term (that is,
stoichiometric coefficient, species name, ``+`` or ``<=>``) in the equation
must be separated by a space.
Reversible reactions may be written using ``<=>`` or ``=`` to separate
reactants and products. Irreversible reactions are written using ``=>``.
``type``
A string specifying the type of reaction or rate coefficient
parameterization. The default is ``elementary``. Reaction types are:
- ``elementary`` (:ref:`details <sec-yaml-elementary>`)
- ``three-body`` (:ref:`details <sec-yaml-three-body>`)
- ``Blowers-Masel`` (:ref:`details <sec-yaml-Blowers-Masel>`)
- ``two-temperature-plasma`` (:ref:`details <sec-yaml-two-temperature-plasma>`)
- ``falloff`` (:ref:`details <sec-yaml-falloff>`)
- ``chemically-activated`` (:ref:`details <sec-yaml-chemically-activated>`)
- ``pressure-dependent-Arrhenius`` (:ref:`details <sec-yaml-pressure-dependent-Arrhenius>`)
- ``Chebyshev`` (:ref:`details <sec-yaml-Chebyshev>`)
- ``linear-Burke`` (:ref:`details <sec-yaml-linear-Burke>`)
Reactions without a specified ``type`` on surfaces or edges are
automatically treated as :ref:`interface-Arrhenius <sec-yaml-interface-Arrhenius>`
reactions, unless a ``sticking-coefficient`` implies a
:ref:`sticking-Arrhenius <sec-yaml-sticking-Arrhenius>` reaction. Interface
reactions that involve charge transfer between phases are automatically treated as
:ref:`electrochemical <sec-yaml-electrochemical-reaction>` reactions.
Reactions on surfaces or edges specifying ``type`` as ``Blowers-Masel`` are treated
as :ref:`interface-Blowers-Masel <sec-yaml-interface-Blowers-Masel>` or
:ref:`sticking-Blowers-Masel <sec-yaml-sticking-Blowers-Masel>`.
``duplicate``
Boolean indicating whether the reaction is a known duplicate of another
reaction. The default is ``false``.
``orders``
An optional mapping of species to explicit reaction orders to use. Reaction
orders for reactant species not explicitly mentioned are taken to be their
respective stoichiometric coefficients. See :ref:`sec-reaction-orders` for
additional information.
``negative-orders``
Boolean indicating whether negative reaction orders are allowed. The
default is ``false``.
``nonreactant-orders``
Boolean indicating whether orders for non-reactant species are allowed.
The default is ``false``.
Depending on the reaction ``type``, other fields may be necessary to specify
the rate of the reaction.
Reaction rate expressions
=========================
.. _sec-yaml-Arrhenius-rate:
Arrhenius
---------
Arrhenius rate expressions are specified as a mapping with fields:
``A``
The pre-exponential factor :math:`A`
``b``
The temperature exponent :math:`b`
``Ea``
The activation energy :math:`E_a`
or a corresponding three-element list. The following are equivalent::
{A: -2.70000E+13 cm^3/mol/s, b: 0, Ea: 355 cal/mol}
[-2.70000E+13 cm^3/mol/s, 0, 355 cal/mol]
.. _sec-yaml-Blowers-Masel-rate:
Blowers-Masel
-------------
Blowers-Masel rate expressions calculate the rate constant based on the Blowers Masel
approximation as :ref:`described here <sec-blowers-masel>`. The rate parameters are
specified as a mapping with fields:
``A``
The pre-exponential factor :math:`A`
``b``
The temperature exponent :math:`b`
``Ea0``
The intrinsic activation energy :math:`E_{a0}`
``w``
The average of the bond dissociation energy of the bond breaking and that being
formed in the reaction :math:`w`
or a corresponding four-element list. The following are equivalent::
{A: 3.87e+04 cm^3/mol/s, b: 2.7, Ea0: 6260.0 cal/mol, w: 1e9 cal/mol}
[3.87e+04 cm^3/mol/s, 2.7, 6260.0 cal/mol, 1e9 cal/mol]
.. _sec-yaml-two-temperature-plasma-rate:
Two-Temperature Plasma
----------------------
Two-temperature plasma reactions involve an electron as one of the reactants, where the
electron temperature may differ from the gas temperature as
:ref:`described here <sec-two-temperature-plasma-rate>`.
The rate parameters are specified as a mapping with fields:
``A``
The pre-exponential factor
``b``
The temperature exponent, which is applied to the electron temperature
``Ea-gas``
The activation energy term :math:`E_{a,g}` that is related to the gas temperature
``Ea-electron``
The activation energy term :math:`E_{a,e}` that is related to the electron
temperature
or a corresponding four-element list. The following are equivalent::
{A: 17283, b: -3.1, Ea-gas: -5820 J/mol, Ea-electron: 1081 J/mol}
[17283, -3.1, -5820 J/mol, 1081 J/mol]
.. _sec-yaml-efficiencies:
Efficiencies
============
Some reaction types include parameters for the "efficiency" of different species
as third-body colliders. For these reactions, the following additional fields
are supported:
``efficiencies``
A mapping of species names to efficiency values
``default-efficiency``
The efficiency for use for species not included in the ``efficiencies``
mapping. Defaults to 1.0.
.. _sec-yaml-rate-types:
Reaction types
==============
.. _sec-yaml-elementary:
``elementary``
--------------
A homogeneous reaction with a pressure-independent rate coefficient and mass action
kinetics, as :ref:`described here <sec-arrhenius-rate>`.
Additional fields are:
``rate-constant``
An :ref:`Arrhenius-type <sec-yaml-Arrhenius-rate>` list or mapping.
``negative-A``
A boolean indicating whether a negative value for the pre-exponential factor
is allowed. The default is ``false``.
Example::
equation: N + NO <=> N2 + O
rate-constant: {A: -2.70000E+13 cm^3/mol/s, b: 0, Ea: 355 cal/mol}
negative-A: true
.. _sec-yaml-three-body:
``three-body``
--------------
A three body reaction as :ref:`described here <sec-three-body-reaction>`.
The reaction equation must include a third body collision partner, which may be either
a specific species or the generic third body ``M``.
Includes the fields of an ``elementary`` reaction, plus the fields for
specifying :ref:`efficiencies <sec-yaml-efficiencies>`.
Example::
equation: 2 O + M = O2 + M
type: three-body
rate-constant: [1.20000E+17 cm^6/mol^2/s, -1, 0]
efficiencies: {AR: 0.83, H2O: 5}
The ``type`` field of the YAML entry may be omitted. Reactions containing the generic
third body M are automatically identified as three-body reactions. Reactions are also
identified as three-body reactions if all of the following conditions are met:
- There is exactly one species appearing as both a reactant and product
- All reactants and products have integral stoichiometric coefficients
- The sum of the stoichiometric coefficients for either the reactants or products is 3.
Examples::
- equation: H + 2 O2 <=> HO2 + O2 # Reaction 34
rate-constant: {A: 2.08e+19, b: -1.24, Ea: 0.0}
- equation: H + O2 + N2 <=> HO2 + N2 # Reaction 36
rate-constant: {A: 2.6e+19, b: -1.24, Ea: 0.0}
.. caution::
If a corresponding reaction with the generic third body M also appears in the
mechanism, such as::
- equation: H + O2 + M <=> HO2 + M # Reaction 33
rate-constant: {A: 2.8e+18, b: -0.86, Ea: 0.0}
efficiencies: {O2: 0.0, H2O: 0.0, CO: 0.75, CO2: 1.5, C2H6: 1.5, N2: 0.0, AR: 0.0}
then the third body efficiency for any third bodies that are given in the explicit
form of Reaction 34 or Reaction 35 above must be set to zero, as shown here for
O2 and N2, or the reactions must be marked as duplicate.
.. versionchanged:: 3.0
Three body reactions are detected automatically and the the ``type`` field may be
omitted. Reactions with explicit third bodies are required to be marked as
duplicates of reactions with the generic third body if the corresponding efficiency
is not zero.
.. versionadded:: 3.1
Reactions with explicit third bodies and the corresponding reaction with "M" issue
warnings instead of raising errors by default. The
:ref:`sec-yaml-phase-explicit-third-body-duplicates` field of the phase entry can be
used to control how these reactions are handled.
.. _sec-yaml-Blowers-Masel:
``Blowers-Masel``
-----------------
Includes the fields of an :ref:`elementary <sec-yaml-elementary>` reaction, except that
the ``rate-constant`` field is a
:ref:`Blowers-Masel-type <sec-yaml-Blowers-Masel-rate>` list or mapping.
Example::
equation: O + H2 <=> H + OH
type: Blowers-Masel
rate-constant: {A: 3.87e+04 cm^2/mol/s, b: 2.7, Ea0: 6260.0 cal/mol, w: 1e9 cal/mol}
.. _sec-yaml-two-temperature-plasma:
``two-temperature-plasma``
--------------------------
Includes the fields of an :ref:`elementary <sec-yaml-elementary>` reaction, except that
the ``rate-constant`` field is a
:ref:`Two-temperature-plasma <sec-yaml-two-temperature-plasma-rate>` list or
mapping.
Example::
equation: O + H => O + H
type: two-temperature-plasma
rate-constant: {A: 17283, b: -3.1, Ea-gas: -5820 J/mol, Ea-electron: 1081 J/mol}
.. _sec-yaml-falloff:
``falloff``
-----------
A falloff reaction as :ref:`described here <sec-falloff-rate>`.
The reaction equation should include the pressure-dependent third body collision
partner ``(+M)`` or ``(+name)`` where ``name`` is the name of a species. The
latter case is equivalent to setting the efficiency for ``name`` to 1 and the
efficiency for all other species to 0.
Includes field for specifying :ref:`efficiencies <sec-yaml-efficiencies>` as well as:
``high-P-rate-constant``
An :ref:`sec-yaml-Arrhenius-rate` expression for the high-pressure limit
``low-P-rate-constant``
An :ref:`sec-yaml-Arrhenius-rate` expression for the low-pressure limit
``Troe``
Parameters for the :ref:`Troe <sec-troe-falloff>` falloff function. A mapping
containing the keys ``A``, ``T3``, ``T1`` and optionally ``T2``. The default value
for ``T2`` is 0.
``SRI``
Parameters for the :ref:`SRI <sec-sri-falloff>` falloff function. A mapping
containing the keys ``A``, ``B``, ``C``, and optionally ``D`` and ``E``. The default
values for ``D`` and ``E`` are 1.0 and 0.0, respectively.
``Tsang``
Parameters for the :ref:`Tsang <sec-tsang-falloff>` falloff function. A mapping
containing the keys ``A`` and ``B``. The default value for ``B`` is 0.0.
Example::
equation: H + CH2 (+ N2) <=> CH3 (+N2)
type: falloff
high-P-rate-constant: [6.00000E+14 cm^3/mol/s, 0, 0]
low-P-rate-constant: {A: 1.04000E+26 cm^6/mol^2/s, b: -2.76, Ea: 1600}
Troe: {A: 0.562, T3: 91, T1: 5836}
.. _sec-yaml-chemically-activated:
``chemically-activated``
------------------------
A chemically activated reaction as
:ref:`described here <sec-chemically-activated-rate>`.
The parameters are the same as for :ref:`sec-yaml-falloff` reactions.
Example::
equation: CH3 + OH (+M) <=> CH2O + H2 (+M)
type: chemically-activated
high-P-rate-constant: [5.88E-14, 6.721, -3022.227]
low-P-rate-constant: [282320.078, 1.46878, -3270.56495]
.. _sec-yaml-pressure-dependent-Arrhenius:
``pressure-dependent-Arrhenius``
--------------------------------
A pressure-dependent reaction using multiple Arrhenius expressions as
:ref:`described here <sec-plog-rate>`.
The only additional field in this reaction type is:
``rate-constants``
A list of mappings, where each mapping is the mapping form of an
:ref:`sec-yaml-Arrhenius-rate` expression with the addition of a pressure ``P``.
Example::
equation: H + CH4 <=> H2 + CH3
type: pressure-dependent-Arrhenius
rate-constants:
- {P: 0.039474 atm, A: 2.720000e+09 cm^3/mol/s, b: 1.2, Ea: 6834.0}
- {P: 1.0 atm, A: 1.260000e+20, b: -1.83, Ea: 15003.0}
- {P: 1.0 atm, A: 1.230000e+04, b: 2.68, Ea: 6335.0}
- {P: 1.01325 MPa, A: 1.680000e+16, b: -0.6, Ea: 14754.0}
.. _sec-yaml-Chebyshev:
``Chebyshev``
-------------
A reaction parameterized as a bivariate Chebyshev polynomial as
:ref:`described here <sec-chebyshev-rate>`.
Additional fields are:
``temperature-range``
A list of two values specifying the minimum and maximum temperatures at
which the rate constant is valid
``pressure-range``
A list of two values specifying the minimum and maximum pressures at
which the rate constant is valid
``data``
A list of lists containing the Chebyshev coefficients
Example::
equation: CH4 <=> CH3 + H
type: Chebyshev
temperature-range: [290, 3000]
pressure-range: [0.0098692326671601278 atm, 98.692326671601279 atm]
data: [[-1.44280e+01, 2.59970e-01, -2.24320e-02, -2.78700e-03],
[ 2.20630e+01, 4.88090e-01, -3.96430e-02, -5.48110e-03],
[-2.32940e-01, 4.01900e-01, -2.60730e-02, -5.04860e-03],
[-2.93660e-01, 2.85680e-01, -9.33730e-03, -4.01020e-03],
[-2.26210e-01, 1.69190e-01, 4.85810e-03, -2.38030e-03],
[-1.43220e-01, 7.71110e-02, 1.27080e-02, -6.41540e-04]]
.. _sec-yaml-linear-Burke:
``linear-Burke``
----------------
A complex-forming reaction (one that depends on both P and X) parameterized according to
the reduced-pressure linear mixture rule as :ref:`described here <sec-linear-Burke>`.
``efficiency`` and ``eig0`` comprise the two acceptable ways to represent the
contribution of each bath gas component (collider) to the reduced pressure. All
explicitly defined colliders must include either ``efficiency`` or ``eig0``, but the
choice must remain consistent throughout a single reaction (either all colliders are
defined with ``efficiency``, or all are defined with ``eig0``).
The pressure-dependent aspect of each collider rate constant can be parameterized in the
user's choice of :ref:`Troe <sec-yaml-falloff>`, :ref:`pressure-dependent-Arrhenius <sec-yaml-pressure-dependent-Arrhenius>`,
or :ref:`Chebyshev <sec-yaml-Chebyshev>` representations. The same parameters used for a
standalone Troe, PLOG, or Chebyshev reaction are then inserted directly below
``efficiency`` or ``eig0`` for a given collider. At minimum, this treatment must be
applied to ``M``. However, additional colliders may also be given their own Troe, PLOG,
or Chebyshev parameterization if so desired. Mixing and matching of types within the
same reaction is allowed (e.g., a PLOG table for ``M``, Troe parameters for ``H2``, and
Chebyshev data for ``NH3``).
A mathematical description of this YAML implementation can be found in Eq. 8 of
:cite:t:`singal2024`.
Additional fields are:
``colliders``
A list of dictionaries, where each entry contains parameters corresponding to
individual colliders (species in the bath gas). Each entry within the ``colliders``
list may contain the following fields:
``name``
The name of the collider species (e.g., ``H2O``). The first collider defined
must be ``M``, which represents the generic reference collider (often ``Ar`` or
``N2``) that represents all species lacking their own explicit parameterization.
``eig0``
The absolute value of the least negative chemically significant eigenvalue of
the master equation for the :math:`i^{th}` collider (when pure), evaluated at
the low-pressure limit, :math:`\Lambda_{0,i}(T)[M]`. The user must explicitly
assign an ``eig0`` for ``M``. This parameter is entered in modified Arrhenius
format to enable consideration of temperature dependence.
``efficiency``
The third-body efficiency of the collider relative to that of the reference
collider ``M``, defined as :math:`\epsilon_{0,i}(T)=\Lambda_{0,i}(T)/\Lambda_{0,\text{M}}(T)`.
The user does not need to assign an ``efficiency`` for ``M``, as it is always
equal to 1 by definition. However, they are free to do so, as long as it takes
the form ``efficiency: {A: 1, b: 0, Ea: 0}`` (no variations are permitted).
This parameter is entered in modified Arrhenius format to enable consideration
of temperature dependence. If the user wishes to specify a
temperature-independent value, then ``A`` can be set to this value and ``b`` and
``Ea`` can be set to 0 (such as ``H2O: {A: 10, b: 0, Ea: 0}``).
A :ref:`Troe <sec-yaml-falloff>` implementation also requires: ``high-P-rate-constant``,
``low-P-rate-constant``, ``Troe`` (do not use the Troe ``efficiencies`` key).
A :ref:`pressure-dependent-Arrhenius <sec-yaml-pressure-dependent-Arrhenius>` implementation
also requires: ``rate-constants``.
A :ref:`Chebyshev <sec-yaml-Chebyshev>` implementation also requires: ``temperature-range``,
``pressure-range``, ``data``.
Examples:
`linear-Burke` *rate with Troe format for the reference collider (N2)*::
equation: H + OH <=> H2O
type: linear-Burke
colliders:
- name: M
type: falloff
low-P-rate-constant: {A: 4.530000e+21, b: -1.820309e+00, Ea: 4.987000e+02}
high-P-rate-constant: {A: 2.510000e+13, b: 2.329303e-01, Ea: -1.142000e+02}
Troe: {A: 9.995044e-01, T3: 1.0e-30, T1: 1.0e+30}
- name: AR
efficiency: {A: 2.20621e-02, b: 4.74036e-01, Ea: -1.13148e+02}
- name: H2O
efficiency: {A: 1.04529e-01, b: 5.50787e-01, Ea: -2.32675e+02}
`linear-Burke` *rate with PLOG format for the reference collider (Ar)*::
equation: H + O2 (+M) <=> HO2 (+M) # Adding '(+M)' is optional
type: linear-Burke
colliders:
- name: M
type: pressure-dependent-Arrhenius
rate-constants:
- {P: 1.316e-02 atm, A: 9.39968e+14, b: -2.14348e+00, Ea: 7.72730e+01}
- {P: 1.316e-01 atm, A: 1.07254e+16, b: -2.15999e+00, Ea: 1.30239e+02}
- {P: 3.947e-01 atm, A: 3.17830e+16, b: -2.15813e+00, Ea: 1.66994e+02}
- {P: 1.000e+00 atm, A: 7.72584e+16, b: -2.15195e+00, Ea: 2.13473e+02}
- {P: 3.000e+00 atm, A: 2.11688e+17, b: -2.14062e+00, Ea: 2.79031e+02}
- {P: 1.000e+01 atm, A: 6.53093e+17, b: -2.13213e+00, Ea: 3.87493e+02}
- {P: 3.000e+01 atm, A: 1.49784e+18, b: -2.10026e+00, Ea: 4.87579e+02}
- {P: 1.000e+02 atm, A: 3.82218e+18, b: -2.07057e+00, Ea: 6.65984e+02}
- name: HE
efficiency: {A: 3.37601e-01, b: 1.82568e-01, Ea: 3.62408e+01}
- name: N2
efficiency: {A: 1.24932e+02, b: -5.93263e-01, Ea: 5.40921e+02}
- name: H2
efficiency: {A: 3.13717e+04, b: -1.25419e+00, Ea: 1.12924e+03}
- name: CO2
efficiency: {A: 1.62413e+08, b: -2.27622e+00, Ea: 1.97023e+03}
- name: NH3
efficiency: {A: 4.97750e+00, b: 1.64855e-01, Ea: -2.80351e+02}
- name: H2O
efficiency: {A: 3.69146e+01, b: -7.12902e-02, Ea: 3.19087e+01}
`linear-Burke` *rate with Chebyshev format for the reference collider (Ar)*::
equation: H2O2 <=> 2 OH
type: linear-Burke
colliders:
- name: M
type: Chebyshev
temperature-range: [200.0, 2000.0]
pressure-range: [1.000e-01 atm, 1.000e+02 atm]
data:
- [-1.58e+01, 8.71e-01, -9.44e-02, -2.81e-03, -4.48e-04, 1.58e-03, -2.51e-04]
- [2.32e+01, 5.27e-01, 2.89e-02, -5.46e-03, 7.08e-04, -3.03e-03, 7.81e-04]
- [-3.80e-01, 8.63e-02, 4.03e-02, -7.23e-03, 5.76e-04, 2.79e-03, -1.49e-03]
- [-1.48e-01, -7.18e-03, 2.21e-02, 6.23e-03, -5.98e-03, -8.22e-06, 1.92e-03]
- [-6.06e-02, -1.42e-02, 1.34e-03, 9.62e-03, 1.70e-03, -3.65e-03, -4.32e-04]
- [-2.46e-02, -9.71e-03, -5.88e-03, 3.05e-03, 5.87e-03, 1.50e-03, -2.01e-03]
- [-1.54e-02, -5.24e-03, -6.91e-03, -5.94e-03, -1.22e-03, 2.17e-03, 1.59e-03]
- name: N2
efficiency: {A: 1.14813e+00, b: 4.60090e-02, Ea: -2.92413e+00}
- name: CO2
efficiency: {A: 8.98839e+01, b: -4.27974e-01, Ea: 2.41392e+02}
- name: H2O2
efficiency: {A: 6.45295e-01, b: 4.26266e-01, Ea: 4.28932e+01}
- name: H2O
efficiency: {A: 1.36377e+00, b: 3.06592e-01, Ea: 2.10079e+02}
.. _sec-yaml-interface-Arrhenius:
``interface-Arrhenius``
-----------------------
A reaction occurring on a surface between two bulk phases, or along an edge at the
intersection of two surfaces, as :ref:`described here <sec-surface-rate>`.
Includes the fields of an :ref:`sec-yaml-elementary` reaction plus:
``coverage-dependencies``
A mapping of species names to coverage dependence parameters, where these
parameters are contained in either a mapping with the fields:
``a``
Coefficient for exponential dependence on the coverage
``m``
Power-law exponent of coverage dependence
``E``
Activation energy dependence on coverage, which uses the same sign convention
as the leading-order activation energy term. This can be a scalar value for
the linear dependency or a list of four values for the polynomial dependency
given in the order of 1st, 2nd, 3rd, and 4th-order coefficients
or a list containing the three elements above, in the given order.
Note that parameters ``a``, ``m`` and ``E`` correspond to parameters
:math:`\eta_{ki}`, :math:`\mu_{ki}` and :math:`\epsilon_{ki}` in Eq 11.113 of
:cite:t:`kee2003`, respectively.
Examples::
- equation: 2 H(s) => H2 + 2 Pt(s)
rate-constant: {A: 3.7e21 cm^2/mol/s, b: 0, Ea: 67400 J/mol}
coverage-dependencies: {H(s): {a: 0, m: 0, E: -6000 J/mol}}
- equation: 2 O(S) => O2 + 2 Pt(S)
rate-constant: {A: 3.7e+21, b: 0, Ea: 213200 J/mol}
coverage-dependencies: {O(S): {a: 0.0, m: 0.0,
E: [1.0e3 J/mol, 3.0e3 J/mol , -7.0e4 J/mol , 5.0e3 J/mol]}
- equation: CH4 + PT(S) + O(S) => CH3(S) + OH(S)
rate-constant: {A: 5.0e+18, b: 0.7, Ea: 4.2e+04}
coverage-dependencies:
O(S): [0, 0, 8000]
PT(S): [0, -1.0, 0]
- equation: 2 O(S) => O2 + 2 Pt(S)
rate-constant: {A: 3.7e+21, b: 0, Ea: 213200 J/mol}
coverage-dependencies:
O(S): [0, 0, [1.0e6, 3.0e6, -7.0e7, 5.0e6]]
.. _sec-yaml-interface-Blowers-Masel:
``interface-Blowers-Masel``
---------------------------
Includes the same fields as :ref:`interface-Arrhenius <sec-yaml-interface-Arrhenius>`,
while using the :ref:`Blowers-Masel <sec-yaml-Blowers-Masel-rate>` parameterization
for the rate constant.
Example::
equation: 2 H(s) => H2 + 2 Pt(s)
type: Blowers-Masel
rate-constant: {A: 3.7e21 cm^2/mol/s, b: 0, Ea0: 67400 J/mol, w: 1000000 J/mol}
coverage-dependencies: {H(s): {a: 0, m: 0, E: -6000 J/mol}}
.. _sec-yaml-sticking-Arrhenius:
``sticking-Arrhenius``
----------------------
A sticking reaction occurring on a surface adjacent to a bulk phase, as
:ref:`described here <sec-sticking-rate>`.
Includes the fields of an :ref:`sec-yaml-interface-Arrhenius` reaction plus:
``sticking-coefficient``
An :ref:`Arrhenius-type <sec-yaml-Arrhenius-rate>` expression for the sticking
coefficient
``Motz-Wise``
A boolean indicating whether to use the Motz-Wise correction factor for sticking
coefficients near unity. Defaults to ``false``.
``sticking-species``
The name of the sticking species. Required if the reaction includes multiple
non-surface species.
Example::
equation: OH + PT(S) => OH(S)
sticking-coefficient: {A: 1.0, b: 0, Ea: 0}
.. _sec-yaml-sticking-Blowers-Masel:
``sticking-Blowers-Masel``
--------------------------
Includes the same fields as :ref:`sticking-Arrhenius <sec-yaml-sticking-Arrhenius>`,
while using the :ref:`Blowers-Masel <sec-yaml-Blowers-Masel-rate>` parameterization
for the sticking coefficient.
Example::
equation: OH + PT(S) => OH(S)
type: Blowers-Masel
sticking-coefficient: {A: 1.0, b: 0, Ea0: 0, w: 100000}
Motz-Wise: true
.. _sec-yaml-electrochemical-reaction:
``electrochemical``
-------------------
Interface reactions involving :ref:`charge transfer <sec-electrochemical-reactions>`
between phases.
Includes the fields of an :ref:`sec-yaml-interface-Arrhenius` reaction, plus:
``beta``
The symmetry factor for the reaction. Default is 0.5.
``exchange-current-density-formulation``
Set to ``true`` if the rate constant parameterizes the exchange current
density. Default is ``false``.
Example::
equation: LiC6 <=> Li+(e) + C6
rate-constant: [5.74, 0.0, 0.0]
beta: 0.4

634
doc/sphinx/yaml/species.md Normal file
View File

@ -0,0 +1,634 @@
(sec-yaml-species)=
# Species
The fields of a `species` entry are:
`name`
: String identifier used for the species. Required.
`composition`
: Mapping that specifies the elemental composition of the species, for example,
`{C: 1, H: 4}`. Required.
`thermo`
: Mapping containing the reference state thermodynamic model specification
and parameters. See [](sec-yaml-species-thermo).
`equation-of-state`
: A mapping or list of mappings. Each mapping contains an equation of state model
specification for the species, any parameters for that model, and any parameters for
interactions with other species. See [](sec-yaml-species-eos).
`critical-parameters`
: Mapping containing parameters related to the critical state of a species. Used in
models that incorporate "real gas" effects, such as [](sec-yaml-eos-redlich-kwong).
See [](sec-yaml-species-crit-props).
`transport`
: Mapping containing the species transport model specification and
parameters. See {ref}`sec-yaml-species-transport`.
`coverage-dependencies`
: Mapping where keys are the names of other species whose coverages affects
thermodynamic properties of this species. The map values are the dependency entries
including `model` and model-specific parameters as
[described here](sec-yaml-species-coverage).
`sites`
: The number of sites occupied by a surface or edge species. Default is 1.
`Debye-Huckel`
: Additional model parameters used in the Debye-Hückel model. See
[](sec-yaml-Debye-Huckel) for more information.
(sec-yaml-species-thermo)=
## Species thermo models
Fields of a species `thermo` entry used by all models are:
`model`
: String specifying the model to be used. Required. Supported model strings are:
- [`NASA7`](sec-yaml-nasa7)
- [`NASA9`](sec-yaml-nasa9)
- [`Shomate`](sec-yaml-shomate)
- [`constant-cp`](sec-yaml-constcp)
- [`piecewise-Gibbs`](sec-yaml-piecewise-gibbs)
`reference-pressure`
: The reference pressure at which the given thermodynamic properties apply.
Defaults to 1 atm.
(sec-yaml-nasa7)=
### NASA 7-coefficient polynomials
The polynomial form [described here](sec-thermo-nasa7), given for one or two temperature
regions. Additional fields of a `NASA7` thermo entry are:
`temperature-ranges`
: A list giving the temperature intervals on which the polynomials are valid. For one
temperature region, this list contains the minimum and maximum temperatures for the
polynomial. For two temperature regions, this list contains the minimum, intermediate,
and maximum temperatures.
`data`
: A list with one item per temperature region, where that item is a 7 item list of
polynomial coefficients. The temperature regions are arranged in ascending order. Note
that this is different from the standard CHEMKIN formulation that uses two temperature
regions listed in descending order.
Example:
```yaml
thermo:
model: NASA7
temperature-ranges: [300.0, 1000.0, 5000.0]
data:
- [3.298677, 0.0014082404, -3.963222e-06, 5.641515e-09,
-2.444854e-12, -1020.8999, 3.950372]
- [2.92664, 0.0014879768, -5.68476e-07, 1.0097038e-10,
-6.753351e-15, -922.7977, 5.980528]
```
(sec-yaml-nasa9)=
### NASA 9-coefficient polynomials
The polynomial form [described here](sec-thermo-nasa9), given for any number of
temperature regions. Additional fields of a `NASA9` thermo entry are:
`temperature-ranges`
: A list giving the temperature intervals on which the polynomials are valid. This list
contains the minimum temperature, the intermediate temperatures between each set pair
of regions, and the maximum temperature.
`data`
: A list with one item per temperature region, where that item is a 9 item list of
polynomial coefficients. The temperature regions are arranged in ascending order.
Example:
```yaml
thermo:
model: NASA9
temperature-ranges: [200.00, 1000.00, 6000.0, 20000]
reference-pressure: 1 bar
data:
- [2.210371497E+04, -3.818461820E+02, 6.082738360E+00, -8.530914410E-03,
1.384646189E-05, -9.625793620E-09, 2.519705809E-12, 7.108460860E+02,
-1.076003744E+01]
- [5.877124060E+05, -2.239249073E+03, 6.066949220E+00, -6.139685500E-04,
1.491806679E-07, -1.923105485E-11, 1.061954386E-15, 1.283210415E+04,
-1.586640027E+01]
- [8.310139160E+08, -6.420733540E+05, 2.020264635E+02, -3.065092046E-02,
2.486903333E-06, -9.705954110E-11, 1.437538881E-15, 4.938707040E+06,
-1.672099740E+03]
```
(sec-yaml-shomate)=
### Shomate polynomials
The polynomial form [described here](sec-thermo-shomate), given for one or two
temperature regions. Additional fields of a `Shomate` thermo entry are:
`temperature-ranges`
: A list giving the temperature intervals on which the polynomials are valid. For one
temperature region, this list contains the minimum and maximum temperatures for the
polynomial. For two temperature regions, this list contains the minimum, intermediate,
and maximum temperatures.
`data`
: A list with one item per temperature region, where that item is a 7 item list of
polynomial coefficients. The temperature regions are arranged in ascending order.
Example:
```yaml
thermo:
model: Shomate
temperature-ranges: [298, 1300, 6000]
reference-pressure: 1 bar
data:
- [25.56759, 6.096130, 4.054656, -2.671301, 0.131021,
-118.0089, 227.3665]
- [35.15070, 1.300095, -0.205921, 0.013550, -3.282780,
-127.8375, 231.7120]
```
(sec-yaml-constcp)=
### Constant heat capacity
The constant heat capacity model [described here](sec-thermo-const-cp). Additional
fields of a `constant-cp` thermo entry are:
`T0`
: The reference temperature. Defaults to 298.15 K.
`h0`
: The molar enthalpy at the reference temperature. Defaults to 0.0.
`s0`
: The molar entropy at the reference temperature. Defaults to 0.0.
`cp0`
: The heat capacity at constant pressure. Defaults to 0.0.
`T-min`
: The minimum temperature at which this thermo data should be used. Defaults to 0.0.
`T-max`
: The maximum temperature at which this thermo data should be used. Defaults to
infinity.
Example:
```yaml
thermo:
model: constant-cp
T0: 1000 K
h0: 9.22 kcal/mol
s0: -3.02 cal/mol/K
cp0: 5.95 cal/mol/K
```
(sec-yaml-piecewise-gibbs)=
### Piecewise Gibbs
A model based on piecewise interpolation of the Gibbs free energy as
{ct}`described here <Mu0Poly>`. Additional fields of a `piecewise-Gibbs` entry are:
`h0`
: The molar enthalpy at the reference temperature of 298.15 K. Defaults to 0.0.
`dimensionless`
: A boolean flag indicating whether the values of the Gibbs free energy are given in a
dimensionless form, that is, divided by $RT$. Defaults to `false`.
`data`
: A mapping of temperatures to values of the Gibbs free energy. The Gibbs free energy
can be either in molar units (if `dimensionless` is `false`) or nondimensionalized by
the corresponding temperature (if `dimensionless` is `true`). A value must be provided
at $T^\circ = 298.15$ K.
`T-min`
: The minimum temperature at which this thermo data should be used. Defaults to 0.0.
`T-max`
: The maximum temperature at which this thermo data should be used. Defaults to
infinity.
Example:
```yaml
thermo:
model: piecewise-Gibbs
h0: -230.015 kJ/mol
dimensionless: true
data: {298.15: -91.50963, 333.15: -85.0}
```
(sec-yaml-species-crit-props)=
## Species critical state parameters
Properties characterizing the critical state of a species can be represented as fields
of a `critical-parameters` entry:
`critical-temperature`
: The critical temperature of the species [K]
`critical-pressure`
: The critical pressure of the species [Pa]
`acentric-factor`
: Pitzer's acentric factor $\omega$ [-]
Example:
```yaml
critical-parameters:
critical-temperature: 32.938
critical-pressure: 1.2858 MPa
acentric-factor: -0.22
```
(sec-yaml-species-eos)=
## Species equation of state models
Species-specific parameters used in the equation of state are defined in the
`equation-of-state` entry, which defines the `model` field as well as additional
model-specific fields.
`model`
: String specifying the model to be used. Required. Supported model strings are:
- [`constant-volume`](sec-yaml-eos-constant-volume)
- [`density-temperature-polynomial`](sec-yaml-eos-density-temperature-polynomial)
- [`HKFT`](sec-yaml-eos-hkft)
- [`liquid-water-IAPWS95`](sec-yaml-eos-liquid-water-iapws95)
- [`molar-volume-temperature-polynomial`](sec-yaml-eos-molar-volume-temperature-polynomial)
- [`Peng-Robinson`](sec-yaml-eos-peng-robinson)
- [`Redlich-Kwong`](sec-yaml-eos-redlich-kwong)
(sec-yaml-eos-constant-volume)=
### Constant volume
A constant volume model as {ct}`described here <PDSS_ConstVol>`.
Any one of the following may be specified:
`molar-volume`
: The molar volume of the species.
`molar-density`
: The molar density of the species.
`density`
: The mass density of the species.
Example:
```yaml
equation-of-state:
model: constant-volume
molar-volume: 1.3 cm^3/mol
```
(sec-yaml-eos-density-temperature-polynomial)=
### Density temperature polynomial
A model in which the density varies with temperature as
{ct}`described here <PDSS_SSVol>`.
Additional fields:
`data`
: Vector of 4 coefficients for a cubic polynomial in temperature
Example:
```yaml
equation-of-state:
model: density-temperature-polynomial
units: {mass: g, length: cm}
data: [0.536504, -1.04279e-4, 3.84825e-9, -5.2853e-12]
```
(sec-yaml-eos-hkft)=
### HKFT
The Helgeson-Kirkham-Flowers-Tanger model for aqueous species as
{ct}`described here <PDSS_HKFT>`.
Additional fields:
`h0`
: Enthalpy of formation at the reference temperature and pressure
`s0`
: Entropy of formation at the reference temperature and pressure
`a`
: 4-element vector containing the coefficients $a_1, \ldots , a_4$
`c`
: 2-element vector containing the coefficients $c_1$ and $c_2$
`omega`
: The $\omega$ parameter at the reference temperature and pressure
Example:
```yaml
equation-of-state:
model: HKFT
h0: -57433. cal/gmol
s0: 13.96 cal/gmol/K
a: [0.1839 cal/gmol/bar, -228.5 cal/gmol,
3.256 cal*K/gmol/bar, -27260. cal*K/gmol]
c: [18.18 cal/gmol/K, -29810. cal*K/gmol]
omega: 33060 cal/gmol
```
(sec-yaml-eos-liquid-water-iapws95)=
### Liquid Water IAPWS95
A detailed equation of state for liquid water as {ct}`described here <PDSS_Water>`.
(sec-yaml-eos-molar-volume-temperature-polynomial)=
### Molar volume temperature polynomial
A model in which the molar volume varies with temperature as
{ct}`described here <PDSS_SSVol>`.
Additional fields:
`data`
: Vector of 4 coefficients for a cubic polynomial in temperature
Example:
```yaml
equation-of-state:
model: molar-volume-temperature-polynomial
data: [0.536504 cm^3/mol, -1.04279e-4 cm^3/mol/K, 3.84825e-9 cm^3/mol/K^2,
-5.2853e-12 cm^3/mol/K^3]
```
(sec-yaml-eos-peng-robinson)=
### Peng-Robinson
A model where species follow the Peng-Robinson real gas equation of state as
{ct}`described here <PengRobinson>`.
Additional fields:
`a`
: Pure-species `a` coefficient [Pa\*m^6/kmol^2]
`b`
: Pure-species `b` coefficient [m^3/kmol]
`acentric-factor`
: Pitzer's acentric factor [-]
`binary-a`
: Optional mapping where the keys are species names and the values are the `a`
coefficients for binary interactions between the two species.
Example:
```yaml
equation-of-state:
model: Peng-Robinson
units: {length: cm, quantity: mol}
a: 5.998873E+11
b: 18.9714
acentric-factor: 0.344
binary-a:
H2: 4 bar*cm^6/mol^2
CO2: 7.897e7 bar*cm^6/mol^2
```
(sec-yaml-eos-redlich-kwong)=
### Redlich-Kwong
A model where species follow the Redlich-Kwong real gas equation of state as
{ct}`described here <RedlichKwongMFTP>`.
Additional fields:
`a`
: Pure-species `a` coefficient. Scalar or list of two values for a temperature-dependent
expression.
`b`
: Pure-species `b` coefficient.
`binary-a`
: Mapping where the keys are species and the values are the `a` coefficients for binary
interactions between the two species.
Example:
```yaml
equation-of-state:
model: Redlich-Kwong
a: [6.45714e+12, 0]
b: 29.65792
binary-a:
H2O: [7.897e+12, 0]
```
(sec-yaml-species-transport)=
## Species transport models
`model`
: String specifying the model type. The only model that is specifically handled is
`gas`.
### Gas transport
Species transport properties are a rare exception to Cantera's use of SI units, and use
the units in which these properties are customarily reported. No conversions are
supported.
The additional fields of a `gas` transport entry are:
`geometry`
: A string specifying the geometry of the molecule. One of `atom`, `linear`, or
`nonlinear`.
`diameter`
: The Lennard-Jones collision diameter [Å]
`well-depth`
: The Lennard-Jones well depth [K]
`dipole`
: The permanent dipole moment [Debye]. Default 0.0.
`polarizability`
: The dipole polarizability [Å^3]. Default 0.0.
`rotational-relaxation`
: The rotational relaxation collision number at 298 K [-]. Default 0.0.
`acentric-factor`
: Pitzer's acentric factor [-]. Default 0.0. This value may also be specified as part of
the [critical-parameters](sec-yaml-species-crit-props) field, in which case the value
provided there supersedes this one.
`dispersion-coefficient`
: The dispersion coefficient, normalized by $e^2$ [Å^5]. Default 0.0.
`quadrupole-polarizability`
: The quadrupole polarizability [Å^5]. Default 0.0.
Example:
```yaml
transport:
model: gas
geometry: linear
well-depth: 107.4
diameter: 3.458
polarizability: 1.6
rotational-relaxation: 3.8
```
(sec-yaml-species-coverage)=
## Species coverage dependencies
The coverage-dependent surface species formulation calculates coverage-dependent
correction factors to the ideal surface phase properties. Used in conjunction with the
[coverage-dependent-surface](sec-yaml-coverage-dependent-surface) phase model.
Full details are {ct}`described here <CoverageDependentSurfPhase>`.
Fields of a species `coverage-dependencies` map entry used by all models are:
`model`
: String specifying the model to be used. Required. Supported model strings are:
- [`linear`](sec-yaml-species-coverage-linear)
- [`polynomial`](sec-yaml-species-coverage-polynomial)
- [`piecewise-linear`](sec-yaml-species-coverage-piecewise-linear)
- [`interpolative`](sec-yaml-species-coverage-interpolative)
(sec-yaml-species-coverage-linear)=
### Linear dependency model
`enthalpy`
: Slope of the coverage-dependent enthalpy.
`entropy`
: Slope of the coverage-dependent entropy.
Example:
```yaml
coverage-dependencies:
O_Pt:
model: linear
units: {energy: eV, quantity: molec}
enthalpy: 0.48
entropy: -0.031
# + other entries (optional)
```
(sec-yaml-species-coverage-polynomial)=
### Polynomial dependency model
`enthalpy-coefficients`
: Array of polynomial coefficients in order of 1st, 2nd, 3rd, and 4th-order used in
coverage-dependent enthalpy calculation.
`entropy-coefficients`
: Array of polynomial coefficients in order of 1st, 2nd, 3rd, and 4th-order used in
coverage-dependent entropy calculation.
Example:
```yaml
coverage-dependencies:
OC_Pt:
model: polynomial
units: {energy: J, quantity: mol}
enthalpy-coefficients: [0.0, -3.86e4, 0.0, 4.2e5]
entropy-coefficients: [0.8e3, 0.0, -1.26e4, 0.0]
# + other entries (optional)
```
(sec-yaml-species-coverage-piecewise-linear)=
### Piecewise-linear dependency model
`enthalpy-low`
: Slope of the coverage-dependent enthalpy for the lower coverage region.
`entropy-low`
: Slope of the coverage-dependent entropy for the lower coverage region.
`enthalpy-high`
: Slope of the coverage-dependent enthalpy for the higher coverage region.
`entropy-high`
: Slope of the coverage-dependent entropy for the higher coverage region.
`enthalpy-change`
: Coverage that separates the lower and higher coverage regions of the
coverage-dependent enthalpy.
`entropy-change`
: Coverage that separates the lower and higher coverage regions of the
coverage-dependent entropy.
`heat-capacity-a`
: Coefficient $c^{(a)}$ used in the
{ct}`coverage-dependent heat capacity <HeatCapacityDependency>` model.
`heat-capacity-b`
: Coefficient $c^{(b)}$ used in the
{ct}`coverage-dependent heat capacity <HeatCapacityDependency>` model.
Example:
```yaml
coverage-dependencies:
CO2_Pt:
model: piecewise-linear
units: {energy: kJ, quantity: mol}
enthalpy-low: 0.5e2
enthalpy-high: 1.0e2
enthalpy-change: 0.4
entropy-low: 0.1e2
entropy-high: -0.2e2
entropy-change: 0.4
heat-capacity-a: 0.02e-1
heat-capacity-b: -0.156e-1
# + other entries (optional)
```
(sec-yaml-species-coverage-interpolative)=
### Interpolative dependency model
`enthalpy-coverages`
: Array of discrete coverage values used in coverage-dependent enthalpy.
`entropy-coverages`
: Array of discrete coverage values used in coverage-dependent entropy.
`enthalpies`
: Array of discrete enthalpy values corresponding to the coverages in
`enthalpy-coverages`.
`entropies`
: Array of discrete entropy values corresponding to the coverages in
`entropy-coverages`.
Example:
```yaml
coverage-dependencies:
C_Pt:
model: interpolative
units: {energy: kcal, quantity: mol}
enthalpy-coverages: [0.0, 0.2, 0.4, 0.7, 0.9, 1.0]
entropy-coverages: [0.0, 0.5, 1.0]
enthalpies: [0.0, 0.5, 1.0, 2.7, 3.5, 4.0]
entropies: [0.0, -0.7, -2.0]
# + other entries (optional)
```

656
doc/sphinx/yaml/species.rst
View File

@ -1,656 +0,0 @@
.. highlight:: yaml
.. _sec-yaml-species:
*******
Species
*******
The fields of a ``species`` entry are:
``name``
String identifier used for the species. Required.
``composition``
Mapping that specifies the elemental composition of the species,
for example, ``{C: 1, H: 4}``. Required.
``thermo``
Mapping containing the reference state thermodynamic model specification
and parameters. See :ref:`sec-yaml-species-thermo`.
``equation-of-state``
A mapping or list of mappings. Each mapping contains an equation of state
model specification for the species, any parameters for that model, and any
parameters for interactions with other species. See
:ref:`sec-yaml-species-eos`.
``critical-parameters``
Mapping containing parameters related to the critical state of a species. Used in
models that incorporate "real gas" effects, such as
:ref:`sec-yaml-eos-redlich-kwong`.
See :ref:`sec-yaml-species-crit-props`.
``transport``
Mapping containing the species transport model specification and
parameters. See :ref:`sec-yaml-species-transport`.
``coverage-dependencies``
Mapping where keys are the names of other species whose coverages affects
thermodynamic properties of this species. The map values are the dependency entries
including ``model`` and model-specific parameters as :ref:`described here
<sec-yaml-species-coverage>`.
``sites``
The number of sites occupied by a surface or edge species. Default is 1.
``Debye-Huckel``
Additional model parameters used in the Debye-Hückel model. See
:ref:`sec-yaml-Debye-Huckel` for more information.
.. _sec-yaml-species-thermo:
Species thermo models
=====================
Fields of a species ``thermo`` entry used by all models are:
``model``
String specifying the model to be used. Required. Supported model strings
are:
- ``NASA7`` (:ref:`details <sec-yaml-nasa7>`)
- ``NASA9`` (:ref:`details <sec-yaml-nasa9>`)
- ``Shomate`` (:ref:`details <sec-yaml-shomate>`)
- ``constant-cp`` (:ref:`details <sec-yaml-constcp>`)
- ``piecewise-Gibbs`` (:ref:`details <sec-yaml-piecewise-gibbs>`)
``reference-pressure``
The reference pressure at which the given thermodynamic properties apply.
Defaults to 1 atm.
.. _sec-yaml-nasa7:
NASA 7-coefficient polynomials
------------------------------
The polynomial form :ref:`described here <sec-thermo-nasa7>`,
given for one or two temperature regions. Additional fields of a ``NASA7``
thermo entry are:
``temperature-ranges``
A list giving the temperature intervals on which the polynomials are valid.
For one temperature region, this list contains the minimum and maximum
temperatures for the polynomial. For two temperature regions, this list
contains the minimum, intermediate, and maximum temperatures.
``data``
A list with one item per temperature region, where that item is a 7 item
list of polynomial coefficients. The temperature regions are arranged in
ascending order. Note that this is different from the standard CHEMKIN
formulation that uses two temperature regions listed in descending order.
Example::
thermo:
model: NASA7
temperature-ranges: [300.0, 1000.0, 5000.0]
data:
- [3.298677, 0.0014082404, -3.963222e-06, 5.641515e-09,
-2.444854e-12, -1020.8999, 3.950372]
- [2.92664, 0.0014879768, -5.68476e-07, 1.0097038e-10,
-6.753351e-15, -922.7977, 5.980528]
.. _sec-yaml-nasa9:
NASA 9-coefficient polynomials
------------------------------
The polynomial form :ref:`described here <sec-thermo-nasa9>`,
given for any number of temperature regions. Additional fields of a ``NASA9``
thermo entry are:
``temperature-ranges``
A list giving the temperature intervals on which the polynomials are valid.
This list contains the minimum temperature, the intermediate temperatures
between each set pair of regions, and the maximum temperature.
``data``
A list with one item per temperature region, where that item is a 9 item
list of polynomial coefficients. The temperature regions are arranged in
ascending order.
Example::
thermo:
model: NASA9
temperature-ranges: [200.00, 1000.00, 6000.0, 20000]
reference-pressure: 1 bar
data:
- [2.210371497E+04, -3.818461820E+02, 6.082738360E+00, -8.530914410E-03,
1.384646189E-05, -9.625793620E-09, 2.519705809E-12, 7.108460860E+02,
-1.076003744E+01]
- [5.877124060E+05, -2.239249073E+03, 6.066949220E+00, -6.139685500E-04,
1.491806679E-07, -1.923105485E-11, 1.061954386E-15, 1.283210415E+04,
-1.586640027E+01]
- [8.310139160E+08, -6.420733540E+05, 2.020264635E+02, -3.065092046E-02,
2.486903333E-06, -9.705954110E-11, 1.437538881E-15, 4.938707040E+06,
-1.672099740E+03]
.. _sec-yaml-shomate:
Shomate polynomials
-------------------
The polynomial form :ref:`described here <sec-thermo-shomate>`,
given for one or two temperature regions. Additional fields of a ``Shomate``
thermo entry are:
``temperature-ranges``
A list giving the temperature intervals on which the polynomials are valid.
For one temperature region, this list contains the minimum and maximum
temperatures for the polynomial. For two temperature regions, this list
contains the minimum, intermediate, and maximum temperatures.
``data``
A list with one item per temperature region, where that item is a 7 item
list of polynomial coefficients. The temperature regions are arranged in
ascending order.
Example::
thermo:
model: Shomate
temperature-ranges: [298, 1300, 6000]
reference-pressure: 1 bar
data:
- [25.56759, 6.096130, 4.054656, -2.671301, 0.131021,
-118.0089, 227.3665]
- [35.15070, 1.300095, -0.205921, 0.013550, -3.282780,
-127.8375, 231.7120]
.. _sec-yaml-constcp:
Constant heat capacity
----------------------
The constant heat capacity model :ref:`described here <sec-thermo-const-cp>`.
Additional fields of a ``constant-cp`` thermo entry are:
``T0``
The reference temperature. Defaults to 298.15 K.
``h0``
The molar enthalpy at the reference temperature. Defaults to 0.0.
``s0``
The molar entropy at the reference temperature. Defaults to 0.0.
``cp0``
The heat capacity at constant pressure. Defaults to 0.0.
``T-min``
The minimum temperature at which this thermo data should be used.
Defaults to 0.0.
``T-max``
The maximum temperature at which this thermo data should be used.
Defaults to infinity.
Example::
thermo:
model: constant-cp
T0: 1000 K
h0: 9.22 kcal/mol
s0: -3.02 cal/mol/K
cp0: 5.95 cal/mol/K
.. _sec-yaml-piecewise-gibbs:
Piecewise Gibbs
---------------
A model based on piecewise interpolation of the Gibbs free energy as
:ct:`described here <Mu0Poly>`. Additional fields of a ``piecewise-Gibbs`` entry are:
``h0``
The molar enthalpy at the reference temperature of 298.15 K. Defaults to
0.0.
``dimensionless``
A boolean flag indicating whether the values of the Gibbs free energy are
given in a dimensionless form, that is, divided by :math:`RT`. Defaults to
``false``.
``data``
A mapping of temperatures to values of the Gibbs free energy. The Gibbs free
energy can be either in molar units (if ``dimensionless`` is ``false``) or
nondimensionalized by the corresponding temperature (if ``dimensionless`` is
``true``). A value must be provided at :math:`T^\circ = 298.15` K.
``T-min``
The minimum temperature at which this thermo data should be used.
Defaults to 0.0.
``T-max``
The maximum temperature at which this thermo data should be used.
Defaults to infinity.
Example::
thermo:
model: piecewise-Gibbs
h0: -230.015 kJ/mol
dimensionless: true
data: {298.15: -91.50963, 333.15: -85.0}
.. _sec-yaml-species-crit-props:
Species critical state parameters
=================================
``critical-temperature``
The critical temperature of the species [K]
``critical-pressure``
The critical pressure of the species [Pa]
``acentric-factor``
Pitzer's acentric factor :math:`omega` [-]
.. _sec-yaml-species-eos:
Species equation of state models
================================
``model``
String specifying the model to be used. Required. Supported model strings
are:
- ``constant-volume`` (:ref:`details <sec-yaml-eos-constant-volume>`)
- ``density-temperature-polynomial`` (:ref:`details <sec-yaml-eos-density-temperature-polynomial>`)
- ``HKFT`` (:ref:`details <sec-yaml-eos-hkft>`)
- ``liquid-water-IAPWS95`` (:ref:`details <sec-yaml-eos-liquid-water-iapws95>`)
- ``molar-volume-temperature-polynomial`` (:ref:`details <sec-yaml-eos-molar-volume-temperature-polynomial>`)
- ``Peng-Robinson`` (:ref:`details <sec-yaml-eos-peng-robinson>`)
- ``Redlich-Kwong`` (:ref:`details <sec-yaml-eos-redlich-kwong>`)
.. _sec-yaml-eos-constant-volume:
Constant volume
---------------
A constant volume model as :ct:`described here <PDSS_ConstVol>`.
Any one of the following may be specified:
``molar-volume``
The molar volume of the species.
``molar-density``
The molar density of the species.
``density``
The mass density of the species.
Example::
equation-of-state:
model: constant-volume
molar-volume: 1.3 cm^3/mol
.. _sec-yaml-eos-density-temperature-polynomial:
Density temperature polynomial
------------------------------
A model in which the density varies with temperature as
:ct:`described here <PDSS_SSVol>`.
Additional fields:
``data``
Vector of 4 coefficients for a cubic polynomial in temperature
Example::
equation-of-state:
model: density-temperature-polynomial
units: {mass: g, length: cm}
data: [0.536504, -1.04279e-4, 3.84825e-9, -5.2853e-12]
.. _sec-yaml-eos-hkft:
HKFT
----
The Helgeson-Kirkham-Flowers-Tanger model for aqueous species as
:ct:`described here <PDSS_HKFT>`.
Additional fields:
``h0``
Enthalpy of formation at the reference temperature and pressure
``s0``
Entropy of formation at the reference temperature and pressure
``a``
4-element vector containing the coefficients :math:`a_1, \ldots , a_4`
``c``
2-element vector containing the coefficients :math:`c_1` and :math:`c_2`
``omega``
The :math:`\omega` parameter at the reference temperature and pressure
Example::
equation-of-state:
model: HKFT
h0: -57433. cal/gmol
s0: 13.96 cal/gmol/K
a: [0.1839 cal/gmol/bar, -228.5 cal/gmol,
3.256 cal*K/gmol/bar, -27260. cal*K/gmol]
c: [18.18 cal/gmol/K, -29810. cal*K/gmol]
omega: 33060 cal/gmol
.. _sec-yaml-eos-liquid-water-iapws95:
Liquid Water IAPWS95
--------------------
A detailed equation of state for liquid water as :ct:`described here <PDSS_Water>`.
.. _sec-yaml-eos-molar-volume-temperature-polynomial:
Molar volume temperature polynomial
-----------------------------------
A model in which the molar volume varies with temperature as
:ct:`described here <PDSS_SSVol>`.
Additional fields:
``data``
Vector of 4 coefficients for a cubic polynomial in temperature
.. _sec-yaml-eos-peng-robinson:
Peng-Robinson
-------------
A model where species follow the Peng-Robinson real gas equation of state as
:ct:`described here <PengRobinson>`.
Additional fields:
``a``
Pure-species ``a`` coefficient [Pa*m^6/kmol^2]
``b``
Pure-species ``b`` coefficient [m^3/kmol]
``acentric-factor``
Pitzer's acentric factor [-]
``binary-a``
Optional mapping where the keys are species names and the values are the ``a``
coefficients for binary interactions between the two species.
Example::
equation-of-state:
model: Peng-Robinson
units: {length: cm, quantity: mol}
a: 5.998873E+11
b: 18.9714
acentric-factor: 0.344
binary-a:
H2: 4 bar*cm^6/mol^2
CO2: 7.897e7 bar*cm^6/mol^2
.. _sec-yaml-eos-redlich-kwong:
Redlich-Kwong
-------------
A model where species follow the Redlich-Kwong real gas equation of state as
:ct:`described here <RedlichKwongMFTP>`.
Additional fields:
``a``
Pure-species ``a`` coefficient. Scalar or list of two values for a
temperature-dependent expression.
``b``
Pure-species ``b`` coefficient.
``binary-a``
Mapping where the keys are species and the values are the ``a``
coefficients for binary interactions between the two species.
.. _sec-yaml-species-transport:
Species transport models
========================
``model``
String specifying the model type. The only model that is specifically
handled is ``gas``.
Gas transport
-------------
Species transport properties are a rare exception to Cantera's use of SI units,
and use the units in which these properties are customarily reported. No
conversions are supported.
The additional fields of a ``gas`` transport entry are:
``geometry``
A string specifying the geometry of the molecule. One of ``atom``,
``linear``, or ``nonlinear``.
``diameter``
The Lennard-Jones collision diameter [Å]
``well-depth``
The Lennard-Jones well depth [K]
``dipole``
The permanent dipole moment [Debye]. Default 0.0.
``polarizability``
The dipole polarizability [Å^3]. Default 0.0.
``rotational-relaxation``
The rotational relaxation collision number at 298 K [-]. Default 0.0.
``acentric-factor``
Pitzer's acentric factor [-]. Default 0.0. This value may also be specified as part
of the :ref:`critical-parameters <sec-yaml-species-crit-props>` field, in which case
the value provided there supersedes this one.
``dispersion-coefficient``
The dispersion coefficient, normalized by :math:`e^2` [Å^5]. Default 0.0.
``quadrupole-polarizability``
The quadrupole polarizability [Å^5]. Default 0.0.
Example::
transport:
model: gas
geometry: linear
well-depth: 107.4
diameter: 3.458
polarizability: 1.6
rotational-relaxation: 3.8
.. _sec-yaml-species-coverage:
Species coverage dependencies
=============================
The coverage-dependent surface species formulation calculates coverage-dependent
correction factors to the ideal surface phase properties. Used in conjunction with the
:ref:`coverage-dependent-surface <sec-yaml-coverage-dependent-surface>` phase model.
Full details are :ct:`described here <CoverageDependentSurfPhase>`.
Fields of a species ``coverage-dependencies`` map entry used by all models are:
``model``
String specifying the model to be used. Required. Supported model strings are:
- ``linear`` (:ref:`details <sec-yaml-species-coverage-linear>`)
- ``polynomial`` (:ref:`details <sec-yaml-species-coverage-polynomial>`)
- ``piecewise-linear`` (:ref:`details <sec-yaml-species-coverage-piecewise-linear>`)
- ``interpolative`` (:ref:`details <sec-yaml-species-coverage-interpolative>`)
.. _sec-yaml-species-coverage-linear:
Linear dependency model
-----------------------
``enthalpy``
Slope of the coverage-dependent enthalpy.
``entropy``
Slope of the coverage-dependent entropy.
Example::
coverage-dependencies:
O_Pt:
model: linear
units: {energy: eV, quantity: molec}
enthalpy: 0.48
entropy: -0.031
# + other entries (optional)
.. _sec-yaml-species-coverage-polynomial:
Polynomial dependency model
---------------------------
``enthalpy-coefficients``
Array of polynomial coefficients in order of 1st, 2nd, 3rd, and
4th-order used in coverage-dependent enthalpy calculation.
``entropy-coefficients``
Array of polynomial coefficients in order of 1st, 2nd, 3rd, and
4th-order used in coverage-dependent entropy calculation.
Example::
coverage-dependencies:
OC_Pt:
model: polynomial
units: {energy: J, quantity: mol}
enthalpy-coefficients: [0.0, -3.86e4, 0.0, 4.2e5]
entropy-coefficients: [0.8e3, 0.0, -1.26e4, 0.0]
# + other entries (optional)
.. _sec-yaml-species-coverage-piecewise-linear:
Piecewise-linear dependency model
---------------------------------
``enthalpy-low``
Slope of the coverage-dependent enthalpy for the lower coverage region.
``entropy-low``
Slope of the coverage-dependent entropy for the lower coverage region.
``enthalpy-high``
Slope of the coverage-dependent enthalpy for the higher coverage region.
``entropy-high``
Slope of the coverage-dependent entropy for the higher coverage region.
``enthalpy-change``
Coverage that separates the lower and higher coverage regions of the
coverage-dependent enthalpy.
``entropy-change``
Coverage that separates the lower and higher coverage regions of the
coverage-dependent entropy.
``heat-capacity-a``
Coefficient :math:`c^{(a)}` used in the
:ct:`coverage-dependent heat capacity <HeatCapacityDependency>` model.
``heat-capacity-b``
Coefficient :math:`c^{(b)}` used in the
:ct:`coverage-dependent heat capacity <HeatCapacityDependency>` model.
Example::
coverage-dependencies:
CO2_Pt:
model: piecewise-linear
units: {energy: kJ, quantity: mol}
enthalpy-low: 0.5e2
enthalpy-high: 1.0e2
enthalpy-change: 0.4
entropy-low: 0.1e2
entropy-high: -0.2e2
entropy-change: 0.4
heat-capacity-a: 0.02e-1
heat-capacity-b: -0.156e-1
# + other entries (optional)
.. _sec-yaml-species-coverage-interpolative:
Interpolative dependency model
------------------------------
``enthalpy-coverages``
Array of discrete coverage values used in coverage-dependent enthalpy.
``entropy-coverages``
Array of discrete coverage values used in coverage-dependent entropy.
``enthalpies``
Array of discrete enthalpy values corresponding to the
coverages in ``enthalpy-coverages``.
``entropies``
Array of discrete entropy values corresponding to the
coverages in ``entropy-coverages``.
Example::
coverage-dependencies:
C_Pt:
model: interpolative
units: {energy: kcal, quantity: mol}
enthalpy-coverages: [0.0, 0.2, 0.4, 0.7, 0.9, 1.0]
entropy-coverages: [0.0, 0.5, 1.0]
enthalpies: [0.0, 0.5, 1.0, 2.7, 3.5, 4.0]
entropies: [0.0, -0.7, -2.0]
# + other entries (optional)

9
doc/sphinx/yaml/yaml2ck.md Normal file
View File

@ -0,0 +1,9 @@
(sec-yaml2ck)=
# YAML to Chemkin conversion
```{eval-rst}
.. argparse::
:module: cantera.yaml2ck
:func: create_argparser
:prog: yaml2ck
```

10
doc/sphinx/yaml/yaml2ck.rst
View File

@ -1,10 +0,0 @@
.. _sec-yaml2ck:
**************************
YAML to Chemkin conversion
**************************
.. argparse::
:module: cantera.yaml2ck
:func: create_argparser
:prog: yaml2ck

1
include/cantera/base/AnyMap.h
View File

@ -34,6 +34,7 @@ namespace Cantera
class AnyBase {
public:
AnyBase() = default;
AnyBase(const AnyBase& other) = default;
virtual ~AnyBase() = default;
AnyBase& operator=(const AnyBase& other);

14
include/cantera/base/Solution.h
View File

@ -70,6 +70,10 @@ public:
//! Set the Transport object directly
virtual void setTransport(shared_ptr<Transport> transport);
//! Retrieve transport model name
//! @since New in %Cantera 3.2
string transportModel();
//! Set the Transport object by name
//! @param model name of transport model; if omitted, the default model is used
//! @since New in %Cantera 3.0
@ -106,7 +110,15 @@ public:
//! Get the number of adjacent phases
size_t nAdjacent() const {
return m_adjacent.size();
return m_adjacent.size();
}
//! Get the name of an adjacent phase by index
string adjacentName(size_t i) const {
if (i < 0 || i >= m_adjacent.size()) {
throw CanteraError("Solution::adjacentName", "Invalid index {}.", i);
}
return m_adjacent.at(i)->name();
}
AnyMap parameters(bool withInput=false) const;

4
include/cantera/base/SolutionArray.h
View File

@ -119,6 +119,10 @@ public:
//! Retrieve associated ThermoPhase object
shared_ptr<ThermoPhase> thermo();
//! Retrieve associated Transport model
//! @since New in %Cantera 3.2
string transportModel();
//! Retrieve list of component names
vector<string> componentNames() const;

20
include/cantera/base/fmt.h
View File

@ -7,13 +7,6 @@
//! the same name in kinetics/Group.h
#define FMT_NO_FMT_STRING_ALIAS
//! Versions 6.2.0 and 6.2.1 of fmtlib do not include this define before they
//! include windows.h, breaking builds on Windows. Fixed in fmtlib 7.0.0 and
//! newer. https://github.com/fmtlib/fmt/pull/1616
#if defined(_WIN32) && !defined(NOMINMAX)
#define NOMINMAX
#endif
#if CT_USE_SYSTEM_FMT
#include <fmt/format.h>
#include <fmt/printf.h>
@ -24,23 +17,10 @@
#include "cantera/ext/fmt/ostream.h"
#endif
#if FMT_VERSION < 80000
template <typename... Args>
void fmt_append(fmt::memory_buffer& b, const std::string& tmpl, Args... args) {
format_to(b, tmpl, args...);
}
namespace fmt {
template <typename T>
T runtime(T arg) {
return arg;
}
}
#else
template <typename... Args>
void fmt_append(fmt::memory_buffer& b, const std::string& tmpl, Args... args) {
format_to(fmt::appender(b), fmt::runtime(tmpl), args...);
}
#endif
#if FMT_VERSION > 100000
#if CT_USE_SYSTEM_FMT

16
include/cantera/base/global.h
View File

@ -53,16 +53,12 @@ class AnyMap;
* function.
*
* %Cantera input files are written using YAML syntax. For more information on using
* YAML files in %Cantera, see the
* [YAML Users' Guide](https://cantera.org/tutorials/yaml/defining-phases.html)
* or the [YAML Input File API Reference](../../../../sphinx/html/yaml/index.html).
* %Cantera provides the
* [`ck2yaml`](https://cantera.org/tutorials/ck2yaml-tutorial.html)
* tool for converting Chemkin-format mechanisms to the YAML format. The utilities
* [`cti2yaml`](https://cantera.org/tutorials/legacy2yaml.html#cti2yaml) and
* [`ctml2yaml`](https://cantera.org/tutorials/legacy2yaml.html#ctml2yaml) should be
* used to convert legacy CTI and XML input files (from %Cantera 2.6 and earlier) to the
* YAML format.
* YAML files in %Cantera, see the [YAML Users' Guide](../userguide/input-tutorial.html)
* or the [YAML Input File API Reference](../yaml/index.html). %Cantera provides the
* [`ck2yaml`](../userguide/ck2yaml-tutorial.html) tool for converting Chemkin-format
* mechanisms to the YAML format. The utilities [`cti2yaml`](../yaml/cti2yaml.html) and
* [`ctml2yaml`](../yaml/ctml2yaml.html) should be used to convert legacy CTI and XML
* input files (from %Cantera 2.6 and earlier) to the YAML format.
*
* @ingroup ioGroup
* @{

1
include/cantera/clib/ct.h
View File

@ -137,7 +137,6 @@ extern "C" {
CANTERA_CAPI size_t kin_nReactions(int n);
CANTERA_CAPI size_t kin_nPhases(int n);
CANTERA_CAPI size_t kin_phaseIndex(int n, const char* ph);
CANTERA_CAPI size_t kin_reactionPhaseIndex(int n);
CANTERA_CAPI double kin_reactantStoichCoeff(int n, int i, int k);
CANTERA_CAPI double kin_productStoichCoeff(int n, int i, int k);
CANTERA_CAPI int kin_getReactionType(int n, int i, size_t len, char* name);

2
include/cantera/clib/ctonedim.h
View File

@ -65,7 +65,7 @@ extern "C" {
CANTERA_CAPI int sim1D_setProfile(int i, int dom, int comp,
size_t np, const double* pos, size_t nv, const double* v);
CANTERA_CAPI int sim1D_setFlatProfile(int i, int dom, int comp, double v);
CANTERA_CAPI int sim1D_show(int i, const char* fname);
CANTERA_CAPI int sim1D_show(int i);
CANTERA_CAPI int sim1D_setTimeStep(int i, double stepsize, size_t ns, const int* nsteps);
CANTERA_CAPI int sim1D_getInitialSoln(int i);
CANTERA_CAPI int sim1D_solve(int i, int loglevel, int refine_grid);

2
include/cantera/clib/ctreactor.h
View File

@ -24,7 +24,7 @@ extern "C" {
CANTERA_CAPI int reactor_setInitialVolume(int i, double v);
CANTERA_CAPI int reactor_setChemistry(int i, int cflag);
CANTERA_CAPI int reactor_setEnergy(int i, int eflag);
CANTERA_CAPI int reactor_insert(int i, int n);
CANTERA_CAPI int reactor_setSolution(int i, int n);
CANTERA_CAPI double reactor_mass(int i);
CANTERA_CAPI double reactor_volume(int i);
CANTERA_CAPI double reactor_density(int i);

1
include/cantera/clib_experimental/.gitignore vendored Normal file
View File

@ -0,0 +1 @@
*.h

25
include/cantera/clib_experimental/README.md Normal file
View File

@ -0,0 +1,25 @@
# Cantera – Experimental CLib Interface
This directory and the associated `src/clib_experimental` folder contain an
experimental re-implementation of Cantera's traditional CLib interface.
## Code Generation
Run the following command from the Cantera root folder:
```
scons doxygen
python3 interfaces/sourcegen/run.py --api=clib --output=.
scons build clib_experimental=y
```
A rudimentary test suite ensures that code performs as expected:
```
scons test-clib-experimental
```
## Status
The experimental CLib Interface is in preview and still missing many features
needed for parity with the traditional CLib interface.

16
include/cantera/equil/MultiPhase.h
View File

@ -88,6 +88,17 @@ public:
*/
void addPhases(MultiPhase& mix);
//! Add a phase to the mixture.
/*!
* This function must be called before the init() function is called,
* which serves to freeze the MultiPhase.
*
* @param p pointer to the phase object
* @param moles total number of moles of all species in this phase
* @since New in %Cantera 3.2.
*/
void addPhase(shared_ptr<ThermoPhase> p, double moles);
//! Add a phase to the mixture.
/*!
* This function must be called before the init() function is called,
@ -575,6 +586,11 @@ private:
//! Vector of the ThermoPhase pointers.
vector<ThermoPhase*> m_phase;
//! Vector of shared ThermoPhase pointers.
//! Contains valid phase entries if added by addPhase(shared_ptr<ThermoPhase>) and
//! null pointers if a phase is added via addPhase(ThermoPhase*).
vector<shared_ptr<ThermoPhase>> m_sharedPhase;
//! Global Stoichiometric Coefficient array
/*!
* This is a two dimensional array m_atoms(m, k). The first index is the

13
include/cantera/kinetics/ElectronCollisionPlasmaRate.h
View File

@ -31,6 +31,8 @@ struct ElectronCollisionPlasmaData : public ReactionData
ReactionData::invalidateCache();
energyLevels.resize(0);
distribution.resize(0);
m_dist_number = -1;
m_level_number = -1;
}
vector<double> energyLevels; //!< electron energy levels
@ -77,7 +79,7 @@ protected:
* k_f = \sqrt{\frac{2e}{m_e}} N_A \int_0^{\infty} \epsilon_V \sigma F_0 d\epsilon_V.
* @f]
*
* For the convience of calculation, the final form becomes,
* For the convenience of calculation, the final form becomes,
*
* @f[
* k_f = 0.5 \sqrt{\frac{2e}{m_e}} N_A \int_0^{\infty} \sigma F_0 d{{\epsilon_V}^2}.
@ -89,6 +91,7 @@ protected:
class ElectronCollisionPlasmaRate : public ReactionRate
{
public:
ElectronCollisionPlasmaRate() = default;
ElectronCollisionPlasmaRate(const AnyMap& node,
@ -135,6 +138,14 @@ public:
return m_crossSections;
}
//! The value of #m_crossSectionsInterpolated [m2]
const vector<double>& crossSectionInterpolated() const {
return m_crossSectionsInterpolated;
}
//! Update the value of #m_crossSectionsInterpolated [m2]
void updateInterpolatedCrossSection(const vector<double>&);
private:
//! electron energy levels [eV]
vector<double> m_energyLevels;

46
include/cantera/kinetics/Kinetics.h
View File

@ -211,25 +211,22 @@ public:
}
}
/**
* Phase where the reactions occur. For heterogeneous mechanisms, one of
* the phases in the list of phases represents the 2D interface or 1D edge
* at which the reactions take place. This method returns the index of the
* phase with the smallest spatial dimension (1, 2, or 3) among the list
* of phases. If there is more than one, the index of the first one is
* returned. For homogeneous mechanisms, the value 0 is returned.
*
* @deprecated Starting in %Cantera 3.0, the reacting phase is always be the
* first phase in the InterfaceKinetics object. To be removed after %Cantera 3.1.
*/
size_t reactionPhaseIndex() const;
/**
* Return pointer to phase where the reactions occur.
* @since New in %Cantera 3.0
*/
shared_ptr<ThermoPhase> reactionPhase() const;
/**
* Return pointer to phase associated with Kinetics by index.
* @param n Index of the ThermoPhase being sought.
* @since New in %Cantera 3.2.
* @see thermo
*/
shared_ptr<ThermoPhase> phase(size_t n=0) const {
return m_thermo[n];
}
/**
* This method returns a reference to the nth ThermoPhase object defined
* in this kinetics mechanism. It is typically used so that member
@ -1407,6 +1404,26 @@ public:
return m_root.lock();
}
//! Register a function to be called if reaction is added.
//! @param id A unique ID corresponding to the object affected by the callback.
//! Typically, this is a pointer to an object that also holds a reference to the
//! Kinetics object.
//! @param callback The callback function to be called after any reaction is added.
//! When the callback becomes invalid (for example, the corresponding object is
//! being deleted, the removeReactionAddedCallback() method must be invoked.
//! @since New in %Cantera 3.1
void registerReactionAddedCallback(void* id, const function<void()>& callback)
{
m_reactionAddedCallbacks[id] = callback;
}
//! Remove the reaction-changed callback function associated with the specified object.
//! @since New in %Cantera 3.1
void removeReactionAddedCallback(void* id)
{
m_reactionAddedCallbacks.erase(id);
}
protected:
//! Cache for saved calculations within each Kinetics object.
ValueCache m_cache;
@ -1530,6 +1547,9 @@ protected:
//! reference to Solution
std::weak_ptr<Solution> m_root;
//! Callback functions that are invoked when the reaction is added.
map<void*, function<void()>> m_reactionAddedCallbacks;
};
}

15
include/cantera/kinetics/Reaction.h
View File

@ -162,6 +162,18 @@ public:
return bool(m_third_body);
}
//! Register a function to be called if setRate is used.
//! @param id A unique ID corresponding to the object affected by the callback.
//! @param callback The callback function to be called after setRate is called.
//! When the callback becomes invalid (for example, the corresponding object is
//! being deleted), the removeSetRateCallback() method must be invoked.
//! @since New in %Cantera 3.2
void registerSetRateCallback(void* id, const function<void()>& callback);
//! Remove the setRate callback function associated with the specified object.
//! @since New in %Cantera 3.2
void removeSetRateCallback(void* id);
protected:
//! Store the parameters of a Reaction needed to reconstruct an identical
//! object using the newReaction(AnyMap&, Kinetics&) function. Does not
@ -183,6 +195,9 @@ protected:
//! Relative efficiencies of third-body species in enhancing the reaction rate
//! (if applicable)
shared_ptr<ThirdBody> m_third_body;
//! Callback functions that are invoked when the rate is replaced.
map<void*, function<void()>> m_setRateCallbacks;
};

56
include/cantera/numerics/AdaptivePreconditioner.h
View File

@ -1,6 +1,6 @@
/**
* @file AdaptivePreconditioner.h Declarations for the class
* AdaptivePreconditioner which is a child class of PreconditionerBase
* AdaptivePreconditioner which is a child class of SystemJacobian
* for preconditioners used by sundials
*/
@ -10,10 +10,7 @@
#ifndef ADAPTIVEPRECONDITIONER_H
#define ADAPTIVEPRECONDITIONER_H
#include "cantera/numerics/PreconditionerBase.h"
#include "cantera/numerics/eigen_sparse.h"
#include "cantera/base/global.h"
#include <iostream>
#include "cantera/numerics/EigenSparseJacobian.h"
namespace Cantera
{
@ -23,45 +20,25 @@ namespace Cantera
//! the preconditioner by a threshold value. It also neglects pressure
//! dependence and third body contributions in its formation and has a
//! finite difference approximation for temperature.
class AdaptivePreconditioner : public PreconditionerBase
class AdaptivePreconditioner : public EigenSparseJacobian
{
public:
AdaptivePreconditioner();
void initialize(size_t networkSize) override;
void reset() override {
m_precon_matrix.setZero();
m_jac_trips.clear();
};
void setup() override;
const string type() const override { return "Adaptive"; }
void setup() override; // deprecated
void factorize() override;
void solve(const size_t stateSize, double* rhs_vector, double* output) override;
void setValue(size_t row, size_t col, double value) override;
void stateAdjustment(vector<double>& state) override;
void updatePreconditioner() override;
int info() const override {
return static_cast<int>(m_solver.info());
}
//! Prune preconditioner elements
void prunePreconditioner();
//! Return semi-analytical Jacobian of an AdaptivePreconditioner object.
//! @ingroup derivGroup
Eigen::SparseMatrix<double> jacobian() {
Eigen::SparseMatrix<double> jacobian_mat(m_dim, m_dim);
jacobian_mat.setFromTriplets(m_jac_trips.begin(), m_jac_trips.end());
return jacobian_mat;
}
//! Return the internal preconditioner matrix
Eigen::SparseMatrix<double> matrix() {
updatePreconditioner();
return m_precon_matrix;
}
//! Get the threshold value for setting elements
double threshold() { return m_threshold; }
@ -92,12 +69,6 @@ public:
m_solver.setFillfactor(fillFactor);
}
//! Print preconditioner contents
void printPreconditioner() override;
//! Print jacobian contents
void printJacobian();
protected:
//! ILUT fill factor
double m_fill_factor = 0;
@ -105,15 +76,6 @@ protected:
//! ILUT drop tolerance
double m_drop_tol = 0;
//! Vector of triples representing the jacobian used in preconditioning
vector<Eigen::Triplet<double>> m_jac_trips;
//! Storage of appropriately sized identity matrix for making the preconditioner
Eigen::SparseMatrix<double> m_identity;
//! Container that is the sparse preconditioner
Eigen::SparseMatrix<double> m_precon_matrix;
//! Solver used in solving the linear system
Eigen::IncompleteLUT<double> m_solver;

29
include/cantera/numerics/EigenSparseDirectJacobian.h Normal file
View File

@ -0,0 +1,29 @@
//! @file EigenSparseDirectJacobian.h
// This file is part of Cantera. See License.txt in the top-level directory or
// at https://cantera.org/license.txt for license and copyright information.
#ifndef EIGENSPARSEDIRECTJACOBIAN_H
#define EIGENSPARSEDIRECTJACOBIAN_H
#include "cantera/numerics/EigenSparseJacobian.h"
namespace Cantera
{
//! A system matrix solver that uses Eigen's sparse direct (LU) algorithm
class EigenSparseDirectJacobian : public EigenSparseJacobian
{
public:
EigenSparseDirectJacobian() = default;
const string type() const override { return "eigen-sparse-direct"; }
void factorize() override;
void solve(const size_t stateSize, double* rhs_vector, double* output) override;
protected:
Eigen::SparseLU<Eigen::SparseMatrix<double>> m_solver;
};
}
#endif

54
include/cantera/numerics/EigenSparseJacobian.h Normal file
View File

@ -0,0 +1,54 @@
//! @file EigenSparseJacobian.h
// This file is part of Cantera. See License.txt in the top-level directory or
// at https://cantera.org/license.txt for license and copyright information.
#ifndef EIGENSPARSEJACOBIAN_H
#define EIGENSPARSEJACOBIAN_H
#include "cantera/numerics/SystemJacobian.h"
#include "cantera/numerics/eigen_sparse.h"
namespace Cantera
{
//! System Jacobians that use Eigen sparse matrices for storage
class EigenSparseJacobian : public SystemJacobian
{
public:
EigenSparseJacobian() = default;
void initialize(size_t networkSize) override;
void reset() override;
void setValue(size_t row, size_t col, double value) override;
void updatePreconditioner() override;
void updateTransient(double rdt, int* mask) override;
//! Return underlying Jacobian matrix
//! @ingroup derivGroup
Eigen::SparseMatrix<double> jacobian();
//! Return the internal preconditioner matrix
Eigen::SparseMatrix<double> matrix() {
updatePreconditioner();
return m_matrix;
}
void printPreconditioner() override;
//! Print jacobian contents
void printJacobian();
protected:
//! Vector of triples representing the jacobian used in preconditioning
vector<Eigen::Triplet<double>> m_jac_trips;
//! Storage of appropriately sized identity matrix for making the preconditioner
Eigen::SparseMatrix<double> m_identity;
//! Container that is the sparse preconditioner
Eigen::SparseMatrix<double> m_matrix;
};
}
#endif

51
include/cantera/numerics/Func1.h
View File

@ -38,7 +38,7 @@ class TimesConstant1;
//! Advanced functors implement expressions that require multiple parameters.
//! The following advanced functor types are implemented:
//! - @c "tabulated-linear" and @c "tabulated-previous" (class Tabulated1),
//! - @c "polynomial3" (class Poly13),
//! - @c "polynomial3" (class Poly1),
//! - @c "Fourier" (class Fourier1),
//! - @c "Gaussian" (class Gaussian1),
//! - @c "Arrhenius" (class Arrhenius1).
@ -82,7 +82,7 @@ public:
virtual ~Func1() = default;
// Func1(const Func1& right) = delete; //! @todo Uncomment after %Cantera 3.1
Func1(const Func1& right) = delete;
Func1& operator=(const Func1& right) = delete;
//! Returns a string describing the type of the function
@ -119,25 +119,6 @@ public:
*/
virtual bool isIdentical(shared_ptr<Func1> other) const;
//! Routine to determine if two functions are the same.
/*!
* @deprecated Deprecated in %Cantera 3.1 and removed thereafter; replaced by
* isIdentical(shared_ptr<Func1>&).
* @todo Restore deleted copy constructor after removal.
*/
virtual bool isIdentical(Func1& other) const;
/**
* @deprecated Deprecated in %Cantera 3.1 and removed thereafter; replaced by
* internal function.
*/
virtual double isProportional(TimesConstant1& other);
/**
* @deprecated Deprecated in %Cantera 3.1 and removed thereafter; replaced by
* internal function.
*/
virtual double isProportional(Func1& other);
//! Write LaTeX string describing function.
virtual string write(const string& arg) const;
@ -537,22 +518,6 @@ public:
return "times-constant";
}
double isProportional(TimesConstant1& other) override {
if (func1_shared()->isIdentical(*other.func1_shared())) {
return (other.c()/c());
} else {
return 0.0;
}
}
double isProportional(Func1& other) override {
if (func1_shared()->isIdentical(other)) {
return 1.0/c();
} else {
return 0.0;
}
}
double eval(double t) const override {
return m_f1->eval(t) * m_c;
}
@ -713,25 +678,21 @@ protected:
* @f]
* with coefficients provided in the order @f$ [a_n, \dots, a_1, a_0] @f$ (consistent
* with MATLAB and NumPy conventions). Note that %Cantera 3.1 reversed the coefficient
* order with respect to its earlier definition. A deprecation cycle is skipped as the
* functor class is not expected to be widely used; the transitional name Poly13 ensures
* that changed behavior does not go unnoticed. The class name will revert to @b Poly1
* after %Cantera 3.1.
* order with respect to its earlier definition.
* @since Changed in %Cantera 3.1.
* @todo Rename to Poly1 after %Cantera 3.1
* @ingroup func1advanced
*/
class Poly13 : public Func1
class Poly1 : public Func1
{
public:
Poly13(size_t n, const double* c) {
Poly1(size_t n, const double* c) {
m_cpoly.resize(n+1);
std::copy(c, c+m_cpoly.size(), m_cpoly.begin());
}
//! Constructor uses @f$ n + 1 @f$ parameters in the following order:
//! @f$ [a_n, \dots, a_1, a_0] @f$
Poly13(const vector<double>& params);
Poly1(const vector<double>& params);
string type() const override {
return "polynomial3";

8
include/cantera/numerics/Integrator.h
View File

@ -8,7 +8,7 @@
#ifndef CT_INTEGRATOR_H
#define CT_INTEGRATOR_H
#include "FuncEval.h"
#include "PreconditionerBase.h"
#include "SystemJacobian.h"
#include "cantera/base/global.h"
#include "cantera/base/AnyMap.h"
@ -91,7 +91,7 @@ public:
/*!
* @param preconditioner preconditioner object used for the linear solver
*/
virtual void setPreconditioner(shared_ptr<PreconditionerBase> preconditioner) {
virtual void setPreconditioner(shared_ptr<SystemJacobian> preconditioner) {
m_preconditioner = preconditioner;
if (preconditioner->preconditionerSide() == "none") {
m_prec_side = PreconditionerSide::NO_PRECONDITION;
@ -123,7 +123,7 @@ public:
}
//! Return preconditioner reference to object
virtual shared_ptr<PreconditionerBase> preconditioner() {
virtual shared_ptr<SystemJacobian> preconditioner() {
return m_preconditioner;
}
@ -296,7 +296,7 @@ protected:
//! Pointer to preconditioner object used in integration which is
//! set by setPreconditioner and initialized inside of
//! ReactorNet::initialize()
shared_ptr<PreconditionerBase> m_preconditioner;
shared_ptr<SystemJacobian> m_preconditioner;
//! Type of preconditioning used in applyOptions
PreconditionerSide m_prec_side = PreconditionerSide::NO_PRECONDITION;
// methods for DAE solvers

131
include/cantera/numerics/PreconditionerBase.h
View File

@ -1,132 +1,15 @@
/**
* @file PreconditionerBase.h Declarations for the class
* PreconditionerBase which is a virtual base class for
* preconditioning systems.
*/
//! @file PreconditionerBase.h
// This file is part of Cantera. See License.txt in the top-level directory or
// at https://cantera.org/license.txt for license and copyright information.
#ifndef PRECONDITIONERBASE_H
#define PRECONDITIONERBASE_H
#ifndef PRECONDITIONERBASE_FACTORY_H
#define PRECONDITIONERBASE_FACTORY_H
#include "cantera/base/ctexceptions.h"
#pragma message("warning: PreconditionerBase.h and class PreconditionerBase are " \
"deprecated and will be removed after Cantera 3.2. Use " \
"SystemJacobian.h and class SystemJacobian.")
namespace Cantera
{
#include "SystemJacobian.h"
/**
* Specifies the side of the system on which the preconditioner is applied. Not all
* methods are supported by all integrators.
*/
enum class PreconditionerSide {
NO_PRECONDITION, //! No preconditioning
LEFT_PRECONDITION, //! Left side preconditioning
RIGHT_PRECONDITION, //! Right side preconditioning
BOTH_PRECONDITION //! Left and right side preconditioning
};
//! PreconditionerBase serves as an abstract type to extend different preconditioners
class PreconditionerBase
{
public:
PreconditionerBase() {}
virtual ~PreconditionerBase() {}
//! Set a value at the specified row and column of the jacobian triplet vector
//! @param row row in the jacobian matrix
//! @param col column in the jacobian matrix
//! @param value value of the element at row and col
virtual void setValue(size_t row, size_t col, double value) {
throw NotImplementedError("PreconditionerBase::setValue");
}
//! Adjust the state vector based on the preconditioner, e.g., Adaptive
//! preconditioning uses a strictly positive composition when preconditioning which
//! is handled by this function
//! @param state a vector containing the state to be updated
virtual void stateAdjustment(vector<double>& state) {
throw NotImplementedError("PreconditionerBase::stateAdjustment");
}
//! Get preconditioner application side for CVODES
string preconditionerSide() const {
return m_precon_side;
}
virtual void setPreconditionerSide(const string& preconSide) {
m_precon_side = preconSide;
}
//! Solve a linear system Ax=b where A is the preconditioner
//! @param[in] stateSize length of the rhs and output vectors
//! @param[in] rhs_vector right hand side vector used in linear system
//! @param[out] output output vector for solution
virtual void solve(const size_t stateSize, double* rhs_vector, double* output) {
throw NotImplementedError("PreconditionerBase::solve");
};
//! Perform preconditioner specific post-reactor setup operations such as factorize.
virtual void setup() {
throw NotImplementedError("PreconditionerBase::setup");
};
//! Reset preconditioner parameters as needed
virtual void reset() {
throw NotImplementedError("PreconditionerBase::reset");
};
//! Called during setup for any processes that need
//! to be completed prior to setup functions used in sundials.
//! @param networkSize the number of variables in the associated reactor network
virtual void initialize(size_t networkSize) {
throw NotImplementedError("PreconditionerBase::initialize");
};
//! Print preconditioner contents
virtual void printPreconditioner() {
throw NotImplementedError("PreconditionerBase::printPreconditioner");
};
//! Transform Jacobian vector and write into
//! preconditioner, P = (I - gamma * J)
virtual void updatePreconditioner() {
throw NotImplementedError("PreconditionerBase::updatePreconditioner");
}
//! Set gamma used in preconditioning
//! @param gamma used in M = I - gamma*J
virtual void setGamma(double gamma) {
m_gamma = gamma;
};
//! Get gamma used in preconditioning
virtual double gamma() {
return m_gamma;
};
//! Set the absolute tolerance in the solver outside of the network initialization
//! @param atol the specified tolerance
virtual void setAbsoluteTolerance(double atol) {
m_atol = atol;
}
protected:
//! Dimension of the preconditioner
size_t m_dim;
//! gamma value used in M = I - gamma*J
double m_gamma = 1.0;
//! bool saying whether or not the preconditioner is initialized
bool m_init = false;
//! Absolute tolerance of the ODE solver
double m_atol = 0;
string m_precon_side = "none";
};
}
#endif

33
include/cantera/numerics/PreconditionerFactory.h
View File

@ -3,34 +3,13 @@
// This file is part of Cantera. See License.txt in the top-level directory or
// at https://cantera.org/license.txt for license and copyright information.
#ifndef PRECONDITIONER_FACTORY_H
#define PRECONDITIONER_FACTORY_H
#ifndef PRECONDITIONERFACTORY_FACTORY_H
#define PRECONDITIONERFACTORY_FACTORY_H
#include "cantera/base/FactoryBase.h"
#pragma message("warning: PreconditionerFactory.h and class PreconditionerFactory " \
"are deprecated and will be removed after Cantera 3.2. Use " \
"SystemJacobianFactory.h and class SystemJacobianFactory.")
namespace Cantera
{
class PreconditionerBase;
//! Factory class to create preconditioner objects
class PreconditionerFactory : public Factory<PreconditionerBase>
{
public:
static PreconditionerFactory* factory();
//! Delete preconditioner factory
void deleteFactory() override;
private:
static PreconditionerFactory* s_factory;
static std::mutex precon_mutex;
PreconditionerFactory();
};
//! Create a Preconditioner object of the specified type
shared_ptr<PreconditionerBase> newPreconditioner(const string& precon);
}
#include "SystemJacobianFactory.h"
#endif

238
include/cantera/numerics/SystemJacobian.h Normal file
View File

@ -0,0 +1,238 @@
//! @file SystemJacobian.h Declarations for class SystemJacobian
// This file is part of Cantera. See License.txt in the top-level directory or
// at https://cantera.org/license.txt for license and copyright information.
#ifndef SYSTEMJACOBIAN_H
#define SYSTEMJACOBIAN_H
#include "cantera/base/ctexceptions.h"
#include "cantera/base/global.h"
namespace Cantera
{
/**
* Specifies the side of the system on which the preconditioner is applied. Not all
* methods are supported by all integrators.
*/
enum class PreconditionerSide {
NO_PRECONDITION, //! No preconditioning
LEFT_PRECONDITION, //! Left side preconditioning
RIGHT_PRECONDITION, //! Right side preconditioning
BOTH_PRECONDITION //! Left and right side preconditioning
};
//! Abstract base class representing Jacobian matrices and preconditioners used in
//! nonlinear solvers.
//!
//! The matrix is initially populated with elements of the (steady-state) Jacobian
//! using the setValue() method.
//!
//! If the object is being used for preconditioning, the preconditioner matrix
//! @f$ M = I - \gamma J @f$ is computed and factorized by calling
//! updatePreconditioner(). If the object is being used for solving a (pseudo-)transient
//! problem, the transient Jacobian @f$ M = J - \alpha \Delta t^{-1} @f$ is computed and
//! factorized by calling the updateTransient() method.
//!
//! Once the system is factorized, the solve() method can be used for preconditioning
//! or solving Newton steps as appropriate.
//!
//! Implementations of this class provide different options for how to store the
//! matrix elements and different algorithms for factorizing the matrix.
class SystemJacobian
{
public:
SystemJacobian() {}
virtual ~SystemJacobian() {}
//! Derived type, corresponding to names registered with SystemJacobianFactory
virtual const string type() const = 0;
//! Set a value at the specified row and column of the jacobian triplet vector
//! @param row row in the jacobian matrix
//! @param col column in the jacobian matrix
//! @param value value of the element at row and col
virtual void setValue(size_t row, size_t col, double value) {
throw NotImplementedError("SystemJacobian::setValue");
}
//! Adjust the state vector based on the preconditioner, e.g., Adaptive
//! preconditioning uses a strictly positive composition when preconditioning which
//! is handled by this function
//! @param state a vector containing the state to be updated
virtual void stateAdjustment(vector<double>& state) {
throw NotImplementedError("SystemJacobian::stateAdjustment");
}
//! Get preconditioner application side for CVODES
string preconditionerSide() const {
return m_precon_side;
}
//! For iterative solvers, set the side where the preconditioner is applied
virtual void setPreconditionerSide(const string& preconSide) {
m_precon_side = preconSide;
}
//! Transform Jacobian vector and write into
//! preconditioner, P = (I - gamma * J)
virtual void updatePreconditioner() {
throw NotImplementedError("SystemJacobian::updatePreconditioner");
}
//! Update the diagonal terms in the Jacobian by using the transient mask
//! @f$ \alpha @f$.
//! @param rdt Reciprocal of the time step [1/s]
//! @param mask Mask for transient terms: 1 if transient, 0 if algebraic.
virtual void updateTransient(double rdt, int* mask) {
throw NotImplementedError("SystemJacobian::updateTransient");
}
//! Solve a linear system using the system matrix *M*
//!
//! The matrix *M* can either be the preconditioner or the transient Jacobian
//! matrix, depending on whether updateTransient() or updatePreconditioner() was
//! called last.
//!
//! @param[in] stateSize length of the rhs and output vectors
//! @param[in] rhs_vector right hand side vector used in linear system
//! @param[out] output output vector for solution
virtual void solve(const size_t stateSize, double* rhs_vector, double* output) {
throw NotImplementedError("SystemJacobian::solve");
};
//! Perform preconditioner specific post-reactor setup operations such as factorize.
//! @deprecated To be removed after %Cantera 3.2. Use updatePreconditioner() and
//! factorize() instead.
virtual void setup() {
throw NotImplementedError("SystemJacobian::setup");
};
//! Reset parameters as needed
virtual void reset() {
throw NotImplementedError("SystemJacobian::reset");
};
//! Called during setup for any processes that need
//! to be completed prior to setup functions used in sundials.
//! @param networkSize the number of variables in the associated reactor network
virtual void initialize(size_t networkSize) {
throw NotImplementedError("SystemJacobian::initialize");
};
//! Used to provide system bandwidth for implementations that use banded matrix
//! storage. Ignored if not needed.
virtual void setBandwidth(size_t bw) {}
//! Print preconditioner contents
virtual void printPreconditioner() {
throw NotImplementedError("SystemJacobian::printPreconditioner");
};
//! Set gamma used in preconditioning
//! @param gamma used in M = I - gamma*J
virtual void setGamma(double gamma) {
m_gamma = gamma;
};
//! Get gamma used in preconditioning
virtual double gamma() {
return m_gamma;
};
//! Set the absolute tolerance in the solver outside of the network initialization
//! @param atol the specified tolerance
virtual void setAbsoluteTolerance(double atol) {
m_atol = atol;
}
//! Get latest status of linear solver. Zero indicates success. Meaning of non-zero
//! values is solver dependent.
virtual int info() const {
throw NotImplementedError("SystemJacobian::info");
}
//! Elapsed CPU time spent computing the Jacobian elements.
double elapsedTime() const {
return m_elapsed;
}
//! Increase the elapsed time by the specified time.
void updateElapsed(double evalTime) {
m_elapsed += evalTime;
}
//! Number of Jacobian evaluations.
int nEvals() const {
return m_nevals;
}
//! Increment the number of times the Jacobian has been evaluated
void incrementEvals() {
m_nevals++;
}
//! Number of times 'incrementAge' has been called since the last evaluation
int age() const {
return m_age;
}
//! Increment the Jacobian age.
void incrementAge() {
m_age++;
}
//! Set the Jacobian age.
void setAge(int age) {
m_age = age;
}
//! Clear collected stats about number of Jacobian evaluations, CPU time spent on
//! Jacobian updates, and the number of Newton steps that have been taken since
//! updating the Jacobian.
void clearStats() {
m_elapsed = 0.0;
m_nevals = 0;
m_age = 100000;
}
protected:
//! Factorize the system matrix. This method should be called at the end of
//! implementations of updatePreconditioner() and updateTransient().
virtual void factorize() {
throw NotImplementedError("SystemJacobian::factorize");
}
//! Dimension of the system
size_t m_dim;
//! gamma value used in M = I - gamma*J
double m_gamma = 1.0;
//! bool saying whether or not the system is initialized
bool m_init = false;
//! Absolute tolerance of the ODE solver
double m_atol = 0;
double m_elapsed = 0.0; //!< Elapsed CPU time taken to compute the Jacobian
int m_nevals = 0; //!< Number of Jacobian evaluations.
int m_age = 100000; //!< Age of the Jacobian (times incrementAge() has been called)
//! For iterative solvers, side of the system to apply the preconditioner on
string m_precon_side = "none";
};
//! @deprecated To be removed after Cantera 3.2. Renamed to SystemJacobian.
class PreconditionerBase : public SystemJacobian
{
PreconditionerBase() {
warn_deprecated("PreconditionerBase::PreconditionerBase",
"To be removed after Cantera 3.2. Renamed to SystemJacobian.");
}
};
}
#endif

42
include/cantera/numerics/SystemJacobianFactory.h Normal file
View File

@ -0,0 +1,42 @@
//! @file SystemJacobianFactory.h
// This file is part of Cantera. See License.txt in the top-level directory or
// at https://cantera.org/license.txt for license and copyright information.
#ifndef SYSTEMJACOBIANFACTORY_FACTORY_H
#define SYSTEMJACOBIANFACTORY_FACTORY_H
#include "cantera/base/FactoryBase.h"
#include "cantera/base/global.h"
namespace Cantera
{
class SystemJacobian;
//! Factory class to create Jacobian objects for use by linear solvers
class SystemJacobianFactory : public Factory<SystemJacobian>
{
public:
static SystemJacobianFactory* factory();
void deleteFactory() override;
private:
static SystemJacobianFactory* s_factory;
static std::mutex jac_mutex;
SystemJacobianFactory();
};
//! Create a SystemJacobian object of the specified type
shared_ptr<SystemJacobian> newSystemJacobian(const string& type);
//! @deprecated To be removed after %Cantera 3.2. Renamed to newSystemJacobian()
inline shared_ptr<SystemJacobian> newPreconditioner(const string& type) {
warn_deprecated("newPreconditioner",
"To be removed after Cantera 3.2. Renamed to newSystemJacobian");
return newSystemJacobian(type);
}
}
#endif

6
include/cantera/oneD/Boundary1D.h
View File

@ -346,15 +346,9 @@ public:
}
void init() override;
void eval(size_t jg, double* xg, double* rg, integer* diagg, double rdt) override;
shared_ptr<SolutionArray> asArray(const double* soln) const override;
void fromArray(SolutionArray& arr, double* soln) override;
//! @deprecated To be removed after Cantera 3.1.
void show(std::ostream& s, const double* x) override;
void show(const double* x) override;
};

36
include/cantera/oneD/Domain1D.h
View File

@ -75,6 +75,13 @@ public:
throw NotImplementedError("Domain1D::setTransport");
}
//! Set transport model by name.
//! @param model String specifying model name.
//! @since New in %Cantera 3.2.
virtual void setTransportModel(const string& model) {
throw NotImplementedError("Domain1D::setTransportModel");
}
//! The container holding this domain.
const OneDim& container() const {
return *m_container;
@ -118,16 +125,6 @@ public:
*/
virtual void init() { }
//! @deprecated Unused. To be removed after Cantera 3.1.
virtual void setInitialState(double* xlocal = 0) {
warn_deprecated("Domain1D::setInitialState", "To be removed after Cantera 3.1.");
}
//! @deprecated Unused. To be removed after Cantera 3.1.
virtual void setState(size_t point, const double* state, double* x) {
warn_deprecated("Domain1D::setState", "To be removed after Cantera 3.1.");
}
/**
* When called, this function should reset "bad" values in the state vector
* such as negative species concentrations. This function may be called
@ -351,11 +348,6 @@ public:
return x[index(n,j)];
}
//! @deprecated To be removed after Cantera 3.1.
virtual void setJac(MultiJac* jac) {
warn_deprecated("Domain1D::setJac", "To be removed after Cantera 3.1.");
}
//! Save the state of this domain as a SolutionArray.
/*!
* @param soln local solution vector for this domain
@ -484,13 +476,6 @@ public:
}
}
//! Print the solution.
//! @deprecated Not implemented. To be removed after Cantera 3.1.
virtual void show(std::ostream& s, const double* x) {
warn_deprecated("Domain1D::show(std::ostream, double*)",
"Not implemented. To be removed after Cantera 3.1.");
}
//! Print the solution.
//! @param x Pointer to the local portion of the system state vector
virtual void show(const double* x);
@ -526,13 +511,6 @@ public:
return m_z;
}
//! @deprecated To be removed after Cantera 3.1. Use z() instead.
double grid(size_t point) const {
warn_deprecated("Domain1D::grid",
"To be removed after Cantera 3.1. Use z() instead.");
return m_z[point];
}
//! called to set up initial grid, and after grid refinement
virtual void setupGrid(size_t n, const double* z);

8
include/cantera/oneD/Flow1D.h
View File

@ -97,7 +97,7 @@ public:
//! Set the transport model
//! @since New in %Cantera 3.0.
void setTransportModel(const string& trans);
void setTransportModel(const string& model) override;
//! Retrieve transport model
//! @since New in %Cantera 3.0.
@ -608,12 +608,6 @@ protected:
//! @} End of Governing Equations
//! Alternate version of evalContinuity with legacy signature.
//! Implemented by StFlow; included here to prevent compiler warnings about shadowed
//! virtual functions.
//! @deprecated To be removed after %Cantera 3.1.
virtual void evalContinuity(size_t j, double* x, double* r, int* diag, double rdt);
/**
* Evaluate the oxidizer axial velocity equation residual.
*

68
include/cantera/oneD/MultiJac.h
View File

@ -7,6 +7,7 @@
#define CT_MULTIJAC_H
#include "cantera/numerics/BandMatrix.h"
#include "cantera/numerics/SystemJacobian.h"
#include "OneDim.h"
namespace Cantera
@ -20,13 +21,16 @@ namespace Cantera
* @ingroup onedUtilsGroup
* @ingroup derivGroup
*/
class MultiJac : public BandMatrix
class MultiJac : public SystemJacobian
{
public:
//! Constructor.
//! @param r The nonlinear system for which to compute the Jacobian.
//! @deprecated To be removed after %Cantera 3.2. Use default constructor instead.
MultiJac(OneDim& r);
MultiJac() = default;
/**
* Evaluates the Jacobian at x0 using finite differences. The unperturbed residual
* function is resid0, which must be supplied on input. The parameter 'rdt' is the
@ -41,68 +45,66 @@ public:
* @param x0 Solution vector at which to evaluate the Jacobian
* @param resid0 Residual vector at x0
* @param rdt Reciprocal of the time step
* @deprecated To be removed after %Cantera 3.2. Jacobian evaluation moved to
* OneDim::evalJacobian().
*/
void eval(double* x0, double* resid0, double rdt);
//! Elapsed CPU time spent computing the Jacobian.
double elapsedTime() const {
return m_elapsed;
void reset() override;
const string type() const override { return "banded-direct"; }
void setValue(size_t row, size_t col, double value) override;
void initialize(size_t nVars) override;
void setBandwidth(size_t bw) override;
void updateTransient(double rdt, integer* mask) override;
void factorize() override {
m_mat.factor();
}
//! Number of Jacobian evaluations.
int nEvals() const {
return m_nevals;
double& value(size_t i, size_t j) {
return m_mat.value(i, j);
}
//! Number of times 'incrementAge' has been called since the last evaluation
int age() const {
return m_age;
double value(size_t i, size_t j) const {
return m_mat.value(i, j);
}
//! Increment the Jacobian age.
void incrementAge() {
m_age++;
void solve(const double* const b, double* const x) {
m_mat.solve(b, x);
}
//! Update the transient terms in the Jacobian by using the transient mask.
void updateTransient(double rdt, integer* mask);
void solve(const size_t stateSize, double* b, double* x) override {
m_mat.solve(b, x);
}
//! Set the Jacobian age.
void setAge(int age) {
m_age = age;
int info() const override {
return m_mat.info();
}
//! Return the transient mask.
//! @deprecated Unused. To be removed after %Cantera 3.2.
vector<int>& transientMask() {
warn_deprecated("MultiJac::transientMask", "To be removed after Cantera 3.2");
return m_mask;
}
//! @deprecated To be removed after Cantera 3.1.
void incrementDiagonal(int j, double d);
protected:
//! Residual evaluator for this Jacobian
/*!
* This is a pointer to the residual evaluator. This object isn't owned by
* this Jacobian object.
*
* @deprecated Unused. To be removed after %Cantera 3.2.
*/
OneDim* m_resid;
OneDim* m_resid = nullptr;
vector<double> m_r1; //!< Perturbed residual vector
double m_rtol = 1e-5; //!< Relative tolerance for perturbing solution components
//! Absolute tolerance for perturbing solution components
double m_atol = sqrt(std::numeric_limits<double>::epsilon());
double m_elapsed = 0.0; //!< Elapsed CPU time taken to compute the Jacobian
BandMatrix m_mat; //!< Underlying matrix storage
vector<double> m_ssdiag; //!< Diagonal of the steady-state Jacobian
//! Transient mask for transient terms, 1 if transient, 0 if steady-state
//! Transient mask for transient terms, 1 if transient, 0 if steady-state.
//! @deprecated Unused. To be removed after %Cantera 3.2.
vector<int> m_mask;
int m_nevals = 0; //!< Number of Jacobian evaluations.
int m_age = 100000; //!< Age of the Jacobian (times incrementAge() has been called)
};
}
#endif

43
include/cantera/oneD/MultiNewton.h
View File

@ -6,7 +6,7 @@
#ifndef CT_MULTINEWTON_H
#define CT_MULTINEWTON_H
#include "MultiJac.h"
#include "OneDim.h"
namespace Cantera
{
@ -37,7 +37,17 @@ public:
//! Compute the undamped Newton step. The residual function is evaluated
//! at `x`, but the Jacobian is not recomputed.
void step(double* x, double* step, OneDim& r, MultiJac& jac, int loglevel);
//! @since Starting in %Cantera 3.2, the Jacobian is accessed via the OneDim object.
void step(double* x, double* step, OneDim& r, int loglevel);
//! @deprecated Use version without MultiJac argument. To be removed after
//! %Cantera 3.2.
void step(double* x, double* stp, OneDim& r, MultiJac& jac, int loglevel) {
warn_deprecated("MultiNewton::step(..., MultiJac&, ...)",
"Use version without MultiJac argument. "
"To be removed after Cantera 3.2");
step(x, stp, r, loglevel);
}
/**
* Return the factor by which the undamped Newton step 'step0'
@ -99,7 +109,6 @@ public:
* @param[out] s1 norm of the subsequent Newton step after taking the damped Newton
* step
* @param[in] r domain object, used for evaluating residuals over all domains
* @param[in] jac Jacobian evaluator
* @param[in] loglevel controls amount of printed diagnostics
* @param[in] writetitle controls if logging title is printed
*
@ -109,9 +118,22 @@ public:
* - `-2` no suitable damping coefficient was found within the maximum iterations.
* - `-3` the current solution `x0` is too close to the solution bounds and the
* step would exceed the bounds on one or more components.
*
* @since Starting in %Cantera 3.2, the Jacobian is accessed via the OneDim object.
*/
int dampStep(const double* x0, const double* step0, double* x1, double* step1,
double& s1, OneDim& r, MultiJac& jac, int loglevel, bool writetitle);
double& s1, OneDim& r, int loglevel, bool writetitle);
//! @deprecated Use version without MultiJac argument. To be removed after
//! %Cantera 3.2.
int dampStep(const double* x0, const double* step0, double* x1, double* step1,
double& s1, OneDim& r, MultiJac& jac, int loglevel, bool writetitle)
{
warn_deprecated("MultiNewton::dampStep(..., MultiJac&, ...)",
"Use version without MultiJac argument. "
"To be removed after Cantera 3.2");
return dampStep(x0, step0, x1, step1, s1, r, loglevel, writetitle);
}
//! Compute the weighted 2-norm of `step`.
double norm2(const double* x, const double* step, OneDim& r) const;
@ -129,8 +151,19 @@ public:
* - `-2` no suitable damping coefficient was found within the maximum iterations.
* - `-3` the current solution `x0` is too close to the solution bounds and the
* step would exceed the bounds on one or more components.
*
* @since Starting in %Cantera 3.2, the Jacobian is accessed via the OneDim object.
*/
int solve(double* x0, double* x1, OneDim& r, MultiJac& jac, int loglevel);
int solve(double* x0, double* x1, OneDim& r, int loglevel);
//! @deprecated Use version without MultiJac argument. To be removed after
//! %Cantera 3.2.
int solve(double* x0, double* x1, OneDim& r, MultiJac& jac, int loglevel) {
warn_deprecated("MultiNewton::solve(..., MultiJac&, ...)",
"Use version without MultiJac argument. "
"To be removed after Cantera 3.2");
return solve(x0, x1, r, loglevel);
}
//! Set options.
//! @param maxJacAge Maximum number of steps that can be taken before requiring

48
include/cantera/oneD/OneDim.h
View File

@ -10,6 +10,7 @@
#include "Domain1D.h"
#include "MultiJac.h"
#include "cantera/numerics/SystemJacobian.h"
namespace Cantera
{
@ -43,9 +44,20 @@ public:
//! @ingroup derivGroup
MultiJac& jacobian();
shared_ptr<SystemJacobian> getJacobian() {
return m_jac;
}
//! Return a reference to the Newton iterator.
MultiNewton& newton();
//! Set the linear solver used to hold the Jacobian matrix and solve linear systems
//! as part of each Newton iteration. The default is a direct, banded solver.
void setLinearSolver(shared_ptr<SystemJacobian> solver);
//! Get the type of the linear solver being used.
shared_ptr<SystemJacobian> linearSolver() const { return m_jac; }
/**
* Solve F(x) = 0, where F(x) is the multi-domain residual function.
*
@ -195,6 +207,17 @@ public:
*/
void eval(size_t j, double* x, double* r, double rdt=-1.0, int count = 1);
/**
* Evaluates the Jacobian at x0 using finite differences.
*
* The Jacobian is computed by perturbing each component of `x0`, evaluating the
* residual function, and then estimating the partial derivatives numerically using
* finite differences to determine the corresponding column of the Jacobian.
*
* @param x0 State vector at which to evaluate the Jacobian
*/
void evalJacobian(double* x0);
//! Return a pointer to the domain global point *i* belongs to.
/*!
* The domains are scanned right-to-left, and the first one with starting
@ -349,6 +372,19 @@ public:
m_time_step_callback = callback;
}
//! Configure perturbations used to evaluate finite difference Jacobian
//! @param relative Relative perturbation (multiplied by the absolute value of
//! each component). Default `1.0e-5`.
//! @param absolute Absolute perturbation (independent of component value).
//! Default `1.0e-10`.
//! @param threshold Threshold below which to exclude elements from the Jacobian
//! Default `0.0`.
void setJacobianPerturbation(double relative, double absolute, double threshold) {
m_jacobianRelPerturb = relative;
m_jacobianAbsPerturb = absolute;
m_jacobianThreshold = threshold;
}
protected:
//! Evaluate the steady-state Jacobian, accessible via jacobian()
//! @param[in] x Current state vector, length size()
@ -363,7 +399,7 @@ protected:
shared_ptr<vector<double>> m_state; //!< Solution vector
unique_ptr<MultiJac> m_jac; //!< Jacobian evaluator
shared_ptr<SystemJacobian> m_jac; //!< Jacobian evaluator
unique_ptr<MultiNewton> m_newt; //!< Newton iterator
double m_rdt = 0.0; //!< reciprocal of time step
bool m_jac_ok = false; //!< if true, Jacobian is current
@ -371,6 +407,9 @@ protected:
size_t m_bw = 0; //!< Jacobian bandwidth
size_t m_size = 0; //!< solution vector size
//! Work arrays used during Jacobian evaluation
vector<double> m_work1, m_work2;
//! All domains comprising the system
vector<shared_ptr<Domain1D>> m_dom;
@ -412,6 +451,13 @@ protected:
//! Maximum number of timesteps allowed per call to solve()
int m_nsteps_max = 500;
//! Threshold for ignoring small elements in Jacobian
double m_jacobianThreshold = 0.0;
//! Relative perturbation of each component in finite difference Jacobian
double m_jacobianRelPerturb = 1e-5;
//! Absolute perturbation of each component in finite difference Jacobian
double m_jacobianAbsPerturb = 1e-10;
private:
//! @name Statistics
//! Solver stats are collected after successfully solving on a particular grid.

Some files were not shown because too many files have changed in this diff Show More