diff --git a/.github/workflows/main.yaml b/.github/workflows/main.yaml index d9a6f5ecb..ba201b9fb 100644 --- a/.github/workflows/main.yaml +++ b/.github/workflows/main.yaml @@ -13,83 +13,39 @@ on: - testing env: - NIKOLA_OUTPUT_DIR: output - WEBSITE_CLONE_DIR: website + SPHINX_OUTPUT_DIR: build/html RSYNC_USER: "ctdeploy" RSYNC_SERVER: "cantera.org" DEPLOY: ${{ github.event_name == 'push' && github.repository_owner == 'Cantera' && (endswith(github.ref, 'main') || endsWith(github.ref, 'testing')) }} jobs: build: - runs-on: ubuntu-20.04 + runs-on: ubuntu-24.04 steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 name: Checkout the repository with: submodules: recursive - path: ${{ env.WEBSITE_CLONE_DIR }} - - uses: actions/checkout@v2 - name: Checkout Cantera repository - with: - submodules: recursive - repository: Cantera/cantera - path: cantera - ref: "3.0" - - uses: actions/checkout@v2 - name: Checkout Cantera 'main' repository - with: - submodules: recursive - repository: Cantera/cantera - path: cantera-dev - - uses: actions/checkout@v2 - name: Checkout Cantera Jupyter repository - with: - repository: Cantera/cantera-jupyter - path: cantera-jupyter - name: Setup Python - uses: actions/setup-python@v2 + uses: actions/setup-python@v5 with: - python-version: 3.9 - architecture: x64 - - name: Upgrade pip - run: python3 -m pip install -U pip setuptools wheel - - name: Get pip cache dir - id: pip-cache - run: echo "::set-output name=dir::$(python3 -m pip cache dir)" - - - name: Cache dependencies - uses: actions/cache@v2 - with: - path: ${{ steps.pip-cache.outputs.dir }} - key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }} - restore-keys: ${{ runner.os }}-pip- - - - name: Install dependencies - run: python3 -m pip install -r requirements.txt - working-directory: ${{ env.WEBSITE_CLONE_DIR }} - - # Parse SCons configuration for development version and move reST file - - name: Parse configuration options from Cantera SConstruct as reST + python-version: 3.13 + - name: Install pdm run: | - cd cantera-dev - python3 `which scons` help --restructured-text --dev --output=scons-config-options-dev.rst - cd .. - mv -f cantera-dev/scons-config-options-dev.rst ${{ env.WEBSITE_CLONE_DIR }}/pages/compiling/ - + python3 -m pip install pdm + pdm install --verbose - name: Build the site - run: NIKOLA_DEBUG=1 nikola build - working-directory: ${{ env.WEBSITE_CLONE_DIR }} + run: pdm run build # Create artifact containing output - name: Create archive for website output run: | - cd ${{ env.WEBSITE_CLONE_DIR }}; \ - tar -czf website.tar.gz ${{ env.NIKOLA_OUTPUT_DIR }} + tar -czf website.tar.gz ${{ env.SPHINX_OUTPUT_DIR }} - name: Store archive of website output - uses: actions/upload-artifact@v2 + uses: actions/upload-artifact@v4 with: - path: ${{ env.WEBSITE_CLONE_DIR }}/website.tar.gz - retention-days: 5 + path: website.tar.gz + retention-days: 14 # 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 @@ -106,17 +62,15 @@ jobs: RSYNC_DEST: "cantera" run: | rsync -avzP --checksum --exclude='*.map' --exclude='*.md5' \ - --delete --delete-excluded --filter='P /mw_headers.git' --filter='P /documentation/dev/*' \ - --filter='P /doc-versions.json' --filter='P /dev' --filter='P /stable' \ - --filter='P /robots.txt' --filter='P .htaccess' \ - "${WEBSITE_CLONE_DIR}/${NIKOLA_OUTPUT_DIR}/" ${RSYNC_USER}@${RSYNC_SERVER}:${RSYNC_DEST} + --delete --delete-excluded --filter='P /mw_headers.git' --filter='P /dev' \ + --filter='P /?.?' --filter='P /stable' \ + "${SPHINX_OUTPUT_DIR}/" ${RSYNC_USER}@${RSYNC_SERVER}:${RSYNC_DEST} - name: Upload the docs if: env.DEPLOY == 'true' && endsWith(github.ref, 'testing') env: RSYNC_DEST: "testing.cantera.org" run: | rsync -avzP --checksum --exclude='*.map' --exclude='*.md5' \ - --delete --delete-excluded --filter='P /mw_headers.git' --filter='P /documentation/dev/*' \ - --filter='P /doc-versions.json' --filter='P /dev' --filter='P /stable' \ - --filter='P /robots.txt' --filter='P .htaccess' \ - "${WEBSITE_CLONE_DIR}/${NIKOLA_OUTPUT_DIR}/" ${RSYNC_USER}@${RSYNC_SERVER}:${RSYNC_DEST} + --delete --delete-excluded --filter='P /mw_headers.git' --filter='P /dev' \ + --filter='P /?.?' --filter='P /stable' \ + "${SPHINX_OUTPUT_DIR}/" ${RSYNC_USER}@${RSYNC_SERVER}:${RSYNC_DEST} diff --git a/.gitignore b/.gitignore index 1bc99ce53..9f95a0b93 100644 --- a/.gitignore +++ b/.gitignore @@ -1,11 +1,6 @@ -# Nikola directories -output/ -cache/ -.doit.db.* -.doit.db* - -# CI Support -.ci_support/ctdeploy_key +/dev-docs +/dev-docs/ +pdm.lock # Byte-compiled / optimized / DLL files __pycache__/ @@ -29,6 +24,7 @@ parts/ sdist/ var/ wheels/ +share/python-wheels/ *.egg-info/ .installed.cfg *.egg @@ -47,14 +43,17 @@ pip-delete-this-directory.txt # Unit test / coverage reports htmlcov/ .tox/ +.nox/ .coverage .coverage.* .cache nosetests.xml coverage.xml *.cover +*.py,cover .hypothesis/ .pytest_cache/ +cover/ # Translations *.mo @@ -64,6 +63,7 @@ coverage.xml *.log local_settings.py db.sqlite3 +db.sqlite3-journal # Flask stuff: instance/ @@ -76,16 +76,49 @@ instance/ docs/_build/ # PyBuilder +.pybuilder/ target/ # Jupyter Notebook .ipynb_checkpoints -# pyenv -.python-version +# IPython +profile_default/ +ipython_config.py -# celery beat schedule file +# pyenv +# For a library or package, you might want to ignore these files since the code is +# intended to run in multiple environments; otherwise, check them in: +# .python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# poetry +# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. +# This is especially recommended for binary packages to ensure reproducibility, and is more +# commonly ignored for libraries. +# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control +#poetry.lock + +# pdm +# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. +#pdm.lock +# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it +# in version control. +# https://pdm.fming.dev/#use-with-ide +.pdm-python + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm +__pypackages__/ + +# Celery stuff celerybeat-schedule +celerybeat.pid # SageMath parsed files *.sage.py @@ -111,9 +144,21 @@ venv.bak/ # mypy .mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# pytype static type analyzer +.pytype/ -# VS Code -.vscode/ +# Cython debug symbols +cython_debug/ -# macOS hidden files -*.DS_Store +# PyCharm +# JetBrains specific template is maintained in a separate JetBrains.gitignore that can +# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore +# and can be added to the global gitignore or merged into this file. For a more nuclear +# option (not recommended) you can uncomment the following to ignore the entire idea folder. +#.idea/ diff --git a/.gitmodules b/.gitmodules index 31a739b9b..e69de29bb 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,3 +0,0 @@ -[submodule "api-docs"] - path = api-docs - url = https://github.com/Cantera/api-docs diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 000000000..aa75bed2a --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,30 @@ +default_language_version: + python: python3.10 +repos: +- repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.4.0 + hooks: + - id: end-of-file-fixer +- repo: https://github.com/pycqa/isort + rev: 5.12.0 + hooks: + - id: isort + language_version: python3 +- repo: https://github.com/psf/black + rev: 23.1.0 + hooks: + - id: black + language_version: python3 +- repo: https://github.com/pycqa/flake8 + rev: 6.0.0 + hooks: + - id: flake8 + language_version: python3 +- repo: https://github.com/pre-commit/mirrors-mypy + rev: v1.1.1 + hooks: + - id: mypy + # Override default --ignore-missing-imports + args: [] + additional_dependencies: + - sphinx diff --git a/Makefile b/Makefile new file mode 100644 index 000000000..d0c3cbf10 --- /dev/null +++ b/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/README.md b/README.md index f47226f09..cc201557e 100644 --- a/README.md +++ b/README.md @@ -1,84 +1,35 @@ # Cantera Website This repository contains the source code for the [cantera.org](https://cantera.org) website. The -site is built using the [Nikola](https://getnikola.com) static site generator. +site is built using the [Sphinx](https://sphinx-doc.org) static site generator. ## To build the website -1. Create a virtual environment for Nikola (i.e., using conda or virtualenv) -2. Clone the Cantera source: `git clone https://github.com/Cantera/cantera.git` -3. Clone the Cantera Jupyter examples: `git clone https://github.com/Cantera/cantera-jupyter.git` -4. Clone the Cantera website source: `git clone https://github.com/Cantera/cantera-website.git` -5. Enter the website repo: `cd cantera-website` -6. Copy the current development documentation: `curl -O https://cantera.org/documentation/dev/dev-docs.tar.bz2` -7. Extract the dev docs: `tar jxf dev-docs.tar.bz2 --strip-components=1 -C api-docs/dev` -8. Inside the website repo, install the required packages: `pip install -r requirements.txt` -9. Build the website and open in browser: `nikola auto -b` or use `nikola serve -p 9000 -b` for different port +### Using pdm (Recommended) -## To add a language of examples +1. Install [`pdm`](https://pdm.fming.dev/latest/). Recommended method is to use `pipx`. +2. Run `pdm install` to create the virtual environment +5. Run `pdm run build` to build the website, or run `pdm run rebuild` to automatically rebuild the website when a page changes. +6. Run a web server to view the website: -1. Copy one of the existing `render_*_examples.py` and `render_*_examples.plugin` -2. Add the source folder as the key and destination folder to the `EXAMPLES_FOLDERS` dictionary in `conf.py` -3. Edit the `render_*_examples.py` file to build the examples -4. See [this blog post](https://bryanwweber.com/writing/personal/2018/12/22/writing-task-plugins-for-nikola/) for more information about building Nikola tasks + ```shell + python -m http.server 8080 --directory build/html + ``` -## To add an example category for Jupyter or Python +7. Open a browser to -1. New example categories are stored in folders in the Jupyter and Python example repositories -2. If new categories (folders) are added to the examples, the appropriate renderer needs to be updated -3. In the Jupyter and Python examples, there's a dictionary called `*_headers`. Each folder of examples has a key in that dictionary. The values are a nested dictionary with three keys: - 1. `name`: The name used on the index page for that category - 2. `files`: An empty list that gets filled with the names of the examples in this category - 3. `summaries`: A empty dictionary that gets filled with keys that are the example filename and values that are the summary from that example -4. Add a new key to that dictionary with the folder name as the key and fill in the `name` key in the nested dictionary and set the `files` and `summaries` keys to the empty list and empty dictionary, respectively +When you're ready to shut things down, close the web server with `C-c` (`CTRL-c`) -## To add a version's release notes +### Using Conda (old instructions that aren't updated) -* To add the latest version's release notes: `nikola new_release` -* To add release notes for a version by its tag name: `nikola new_release -t {tag_name}` - - Example: `nikola new_release -t v2.4.0` -* To add release notes for a version by its release ID: `nikola new_release -i {id}` - - Example: `nikola new_release -i 12508904` +1. Create a virtual environment for Sphinx using `conda` and activate it. The environment must have Python 3.10 and the `conda-lock` package. +2. Clone the Cantera website source: `git clone https://github.com/Cantera/cantera-website.git` +3. Enter the website repo: `cd cantera-website` +4. Inside the website repo, install the required packages: -## Cheat sheet for linking to content in various places: -* To link to another section on the same page (using the title of the section): - `Governing Equations for Single Reactors`_ -* To link to an external site: - * `YAML 1.2 `__ -* To link to a Python class: - * :py:class:`ConstPressureReactor` -* To link to a C++ class: - * `ThermoPhase <{{% ct_docs doxygen/html/dc/d38/classCantera_1_1ThermoPhase.html %}}>`__ -* To link to an example: - * `IC engine example `__ -* To link to a label in the YAML API docs: - * :ref:`three-body ` + ```shell + conda-lock install continuous-integration/conda-lock.yml --name + ``` -## Apache configuration -To allow the version switcher to work smoothly between Cantera =< 3.0 and Cantera >= 3.1 -(where the directory structure changed significantly), we rely on several `mod_rewrite` -rules, implemented in `.htaccess` files: - -* `/dev/.htaccess`: -```conf -RewriteBase "/dev/" - -RewriteRule "^cython/(.+)" "python/$1" [R] -``` - -* `/documentation/.htaccess`: -```conf -RewriteBase "/documentation/" - -RewriteRule "^dev/sphinx/html/cython/(.*)" "../dev/python/$1" [R] -RewriteRule "^docs-3.0/sphinx/html/python/(.*)" "docs-3.0/sphinx/html/cython/$1" [R] -RewriteRule "^dev/sphinx/html/(.+)" "../dev/$1" [R] -``` - -* `/stable/.htaccess`: -```conf -RewriteBase "/stable/" - -RewriteRule "^cxx(.*)" "../documentation/docs-3.0/doxygen/html/$1" -RewriteRule "^(.*)" "../documentation/docs-3.0/sphinx/html/$1" -``` +5. Build the website and open in browser: `make html && python -m http.server --directory build/html` then navigate to `localhost:8000` in your browser +6. Press `C-c` (`CTRL-C`) to close the Python HTTP server diff --git a/api-docs b/api-docs deleted file mode 160000 index 3fbcedd05..000000000 --- a/api-docs +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 3fbcedd0542a2219c538e06c06c16980a3296896 diff --git a/conf.py b/conf.py deleted file mode 100644 index 69216f1c1..000000000 --- a/conf.py +++ /dev/null @@ -1,1340 +0,0 @@ -# -*- coding: utf-8 -*- - -import time -import os - -# !! This is the configuration of Nikola. !! # -# !! You should edit it to your liking. !! # - - -# ! Some settings can be different in different languages. -# ! A comment stating (translatable) is used to denote those. -# ! There are two ways to specify a translatable setting: -# ! (a) BLOG_TITLE = "My Blog" -# ! (b) BLOG_TITLE = {"en": "My Blog", "es": "Mi Blog"} -# ! Option (a) is used when you don't want that setting translated. -# ! Option (b) is used for settings that are different in different languages. - - -# Data about this site -BLOG_AUTHOR = "Cantera Developers" # (translatable) -BLOG_TITLE = "Cantera" # (translatable) -# This is the main URL for your site. It will be used -# in a prominent link. Don't forget the protocol (http/https)! -SITE_URL = "https://cantera.org/" -# This is the URL where Nikola's output will be deployed. -# If not set, defaults to SITE_URL -# Don't forget the protocol and trailing slash -BASE_URL = "https://cantera.org/" -BLOG_EMAIL = "steering@cantera.org" -BLOG_DESCRIPTION = "This site is for the Cantera software" # (translatable) - -# The most recent major release version of Cantera -CANTERA_VERSION = "3.0" - -# The default context used when looking up :class: or :func: roles -# Options are 'py', 'cti', or 'mat' -DEFAULT_CONTEXT = "py" - -# Nikola is multilingual! -# -# Currently supported languages are: -# -# en English -# ar Arabic -# az Azerbaijani -# bg Bulgarian -# bs Bosnian -# ca Catalan -# cs Czech [ALTERNATIVELY cz] -# da Danish -# de German -# el Greek [NOT gr] -# eo Esperanto -# es Spanish -# et Estonian -# eu Basque -# fa Persian -# fi Finnish -# fr French -# gl Galician -# he Hebrew -# hi Hindi -# hr Croatian -# hu Hungarian -# id Indonesian -# it Italian -# ja Japanese [NOT jp] -# ko Korean -# lt Lithuanian -# nb Norwegian (Bokmål) -# nl Dutch -# pa Punjabi -# pl Polish -# pt Portuguese -# pt_br Portuguese (Brazil) -# ru Russian -# sk Slovak -# sl Slovene -# sq Albanian -# sr Serbian (Cyrillic) -# sr_latin Serbian (Latin) -# sv Swedish -# te Telugu -# th Thai -# tr Turkish [NOT tr_TR] -# uk Ukrainian -# ur Urdu -# zh_cn Chinese (Simplified) -# zh_tw Chinese (Traditional) -# -# If you want to use Nikola with a non-supported language you have to provide -# a module containing the necessary translations -# (cf. the modules at nikola/data/themes/base/messages/). -# If a specific post is not translated to a language, then the version -# in the default language will be shown instead. - -# What is the default language? -DEFAULT_LANG = "en" - -# What other languages do you have? -# The format is {"translationcode" : "path/to/translation" } -# the path will be used as a prefix for the generated pages location -TRANSLATIONS = { - DEFAULT_LANG: "", - # Example for another language: - # "es": "./es", -} - -# What will translated input files be named like? - -# If you have a page something.rst, then something.pl.rst will be considered -# its Polish translation. -# (in the above example: path == "something", ext == "rst", lang == "pl") -# this pattern is also used for metadata: -# something.meta -> something.pl.meta - -TRANSLATIONS_PATTERN = "{path}.{lang}.{ext}" - -# Links for the sidebar / navigation bar. (translatable) -# This is a dict. The keys are languages, and values are tuples. -# -# For regular links: -# ('https://getnikola.com/', 'Nikola Homepage') -# -# For submenus: -# ( -# ( -# ('https://apple.com/', 'Apple'), -# ('https://orange.com/', 'Orange'), -# ), -# 'Fruits' -# ) -# -# WARNING: Support for submenus is theme-dependent. -# Only one level of submenus is supported. -# WARNING: Some themes, including the default Bootstrap 4 theme, -# may present issues if the menu is too large. -# (in Bootstrap, the navbar can grow too large and cover contents.) -# WARNING: If you link to directories, make sure to follow -# ``STRIP_INDEXES``. If it’s set to ``True``, end your links -# with a ``/``, otherwise end them with ``/index.html`` — or -# else they won’t be highlighted when active. - -NAVIGATION_LINKS = { - DEFAULT_LANG: ( - ("/install/index.html", "Install"), - ("/tutorials/index.html", "Tutorials"), - ("/examples/index.html", "Examples"), - ("/community.html", "Community"), - ("/science/index.html", "Science"), - ("/documentation/index.html", "Documentation"), - ("/blog/index.html", "Blog"), - ) -} - -# Alternative navigation links. Works the same way NAVIGATION_LINKS does, -# although themes may not always support them. (translatable) -# (Bootstrap 4: right-side of navbar, Bootblog 4: right side of title) -NAVIGATION_ALT_LINKS = {DEFAULT_LANG: {}} - -# Name of the theme to use. -THEME = "cantera" - -# Primary color of your theme. This will be used to customize your theme. -# Must be a HEX value. -THEME_COLOR = "#5670d4" - -# Theme configuration. Fully theme-dependent. (translatable) -# Examples below are for bootblog4. -THEME_CONFIG = {DEFAULT_LANG: {"navbar_light": True}} - -# POSTS and PAGES contains (wildcard, destination, template) tuples. -# (translatable) -# -# The wildcard is used to generate a list of source files -# (whatever/thing.rst, for example). -# -# That fragment could have an associated metadata file (whatever/thing.meta), -# and optionally translated files (example for Spanish, with code "es"): -# whatever/thing.es.rst and whatever/thing.es.meta -# -# This assumes you use the default TRANSLATIONS_PATTERN. -# -# From those files, a set of HTML fragment files will be generated: -# cache/whatever/thing.html (and maybe cache/whatever/thing.html.es) -# -# These files are combined with the template to produce rendered -# pages, which will be placed at -# output/TRANSLATIONS[lang]/destination/pagename.html -# -# where "pagename" is the "slug" specified in the metadata file. -# The page might also be placed in /destination/pagename/index.html -# if PRETTY_URLS are enabled. -# -# The difference between POSTS and PAGES is that POSTS are added -# to feeds, indexes, tag lists and archives and are considered part -# of a blog, while PAGES are just independent HTML pages. -# -# Finally, note that destination can be translated, i.e. you can -# specify a different translation folder per language. Example: -# PAGES = ( -# ("pages/*.rst", {"en": "pages", "de": "seiten"}, "page.tmpl"), -# ("pages/*.md", {"en": "pages", "de": "seiten"}, "page.tmpl"), -# ) - -POSTS = ( - ("posts/*.rst", "blog", "post.tmpl"), - ("posts/*.md", "blog", "post.tmpl"), - ("posts/*.txt", "blog", "post.tmpl"), - ("posts/*.html", "blog", "post.tmpl"), - ("posts/*.ipynb", "blog", "post.tmpl"), -) -PAGES = ( - ("pages/*.rst", "", "page.tmpl"), - ("pages/*.md", "", "page.tmpl"), - ("pages/*.txt", "", "page.tmpl"), - ("pages/*.html", "", "page.tmpl"), - ("pages/*.ipynb", "", "page.tmpl"), -) - - -# Below this point, everything is optional - -# Post's dates are considered in UTC by default, if you want to use -# another time zone, please set TIMEZONE to match. Check the available -# list from Wikipedia: -# https://en.wikipedia.org/wiki/List_of_tz_database_time_zones -# (e.g. 'Europe/Zurich') -# Also, if you want to use a different time zone in some of your posts, -# you can use the ISO 8601/RFC 3339 format (ex. 2012-03-30T23:00:00+02:00) -TIMEZONE = "America/New_York" - -# If you want to use ISO 8601 (also valid RFC 3339) throughout Nikola -# (especially in new_post), set this to True. -# Note that this does not affect DATE_FORMAT. -# FORCE_ISO8601 = False - -# Date format used to display post dates. (translatable) -# (str used by datetime.datetime.strftime) -# DATE_FORMAT = '%Y-%m-%d %H:%M' - -# Date format used to display post dates, if local dates are used. (translatable) -# (str used by moment.js) -# JS_DATE_FORMAT = 'YYYY-MM-DD HH:mm' - -# Date fanciness. -# -# 0 = using DATE_FORMAT and TIMEZONE -# 1 = using JS_DATE_FORMAT and local user time (via moment.js) -# 2 = using a string like “2 days ago” -# -# Your theme must support it, Bootstrap already does. -# DATE_FANCINESS = 0 - -# While Nikola can select a sensible locale for each language, -# sometimes explicit control can come handy. -# In this file we express locales in the string form that -# python's locales will accept in your OS, by example -# "en_US.utf8" in Unix-like OS, "English_United States" in Windows. -# LOCALES = dict mapping language --> explicit locale for the languages -# in TRANSLATIONS. You can omit one or more keys. -# LOCALE_FALLBACK = locale to use when an explicit locale is unavailable -# LOCALE_DEFAULT = locale to use for languages not mentioned in LOCALES; if -# not set the default Nikola mapping is used. - -# LOCALES = {} -# LOCALE_FALLBACK = None -# LOCALE_DEFAULT = None - -# One or more folders containing files to be copied as-is into the output. -# The format is a dictionary of {source: relative destination}. - -# This is the "production" version of this dictionary -DOCS_FOLDERS = { - "api-docs/dev": "documentation/dev", - "api-docs/docs-2.0": "documentation/docs-2.0", - "api-docs/docs-2.1": "documentation/docs-2.1", - "api-docs/docs-2.2": "documentation/docs-2.2", - "api-docs/docs-2.3": "documentation/docs-2.3", - "api-docs/docs-2.4": "documentation/docs-2.4", - "api-docs/docs-2.5": "documentation/docs-2.5", - "api-docs/docs-2.6": "documentation/docs-2.6", - "api-docs/docs-3.0": "documentation/docs-3.0", -} - -FILES_FOLDERS = {"files/survey2013": "survey2013", "files/license": ""} - -# This is the "development" version of this dictionary -# DOCS_FOLDERS = { -# '../cantera/build/docs': 'documentation/docs-{}'.format(CANTERA_VERSION), -# '../cantera/build/dev-docs': 'documentation/dev', -# 'api-docs/docs-2.0': 'documentation/docs-2.0', -# 'api-docs/docs-2.1': 'documentation/docs-2.1', -# 'api-docs/docs-2.2': 'documentation/docs-2.2', -# 'api-docs/docs-2.3': 'documentation/docs-2.3', -# } - -# One or more folders containing code listings to be processed and published on -# the site. The format is a dictionary of {source: relative destination}. -# Default is: -EXAMPLES_FOLDERS = { - "../cantera/samples/python": "examples/python", - "../cantera-jupyter": "examples/jupyter", - "../cantera/samples/matlab": "examples/matlab", - "../cantera/samples/cxx": "examples/cxx", - "../cantera/samples/f90": "examples/fortran" -} -# Which means process listings from 'listings' into 'output/listings' - -# A mapping of languages to file-extensions that represent that language. -# Feel free to add or delete extensions to any list, but don't add any new -# compilers unless you write the interface for it yourself. -# -# 'rest' is reStructuredText -# 'markdown' is Markdown -# 'html' assumes the file is HTML and just copies it -COMPILERS = { - "rest": (".rst", ".txt"), - "markdown": (".md", ".mdown", ".markdown"), - "textile": (".textile",), - "txt2tags": (".t2t",), - "bbcode": (".bb",), - "wiki": (".wiki",), - "ipynb": (".ipynb",), - "html": (".html", ".htm"), - # PHP files are rendered the usual way (i.e. with the full templates). - # The resulting files have .php extensions, making it possible to run - # them without reconfiguring your server to recognize them. - "php": (".php",), - # Pandoc detects the input from the source filename - # but is disabled by default as it would conflict - # with many of the others. - # "pandoc": ('.rst', '.md', '.txt'), -} - -# Create by default posts in one file format? -# Set to False for two-file posts, with separate metadata. -# ONE_FILE_POSTS = True - -# Preferred metadata format for new posts -# "Nikola": reST comments, wrapped in a HTML comment if needed (default) -# "YAML": YAML wrapped in "---" -# "TOML": TOML wrapped in "+++" -# "Pelican": Native markdown metadata or reST docinfo fields. Nikola style for other formats. -# METADATA_FORMAT = "Nikola" - -# Use date-based path when creating posts? -# Can be enabled on a per-post basis with `nikola new_post -d`. -# The setting is ignored when creating pages. -# NEW_POST_DATE_PATH = False - -# What format to use when creating posts with date paths? -# Default is '%Y/%m/%d', other possibilities include '%Y' or '%Y/%m'. -# NEW_POST_DATE_PATH_FORMAT = '%Y/%m/%d' - -# If this is set to True, the DEFAULT_LANG version will be displayed for -# untranslated posts. -# If this is set to False, then posts that are not translated to a language -# LANG will not be visible at all in the pages in that language. -# SHOW_UNTRANSLATED_POSTS = True - -# Nikola supports logo display. If you have one, you can put the URL here. -# Final output is . -# The URL may be relative to the site root. -LOGO_URL = "/assets/img/cantera-logo.png" - -# If you want to hide the title of your website (for example, if your logo -# already contains the text), set this to False. -SHOW_BLOG_TITLE = False - -# Writes tag cloud data in form of tag_cloud_data.json. -WRITE_TAG_CLOUD = False - -# Paths for different autogenerated bits. These are combined with the -# translation paths. - -# Final locations are: -# output / TRANSLATION[lang] / TAG_PATH / index.html (list of tags) -# output / TRANSLATION[lang] / TAG_PATH / tag.html (list of posts for a tag) -# output / TRANSLATION[lang] / TAG_PATH / tag RSS_EXTENSION (RSS feed for a tag) -# (translatable) -# TAG_PATH = "categories" - -# By default, the list of tags is stored in -# output / TRANSLATION[lang] / TAG_PATH / index.html -# (see explanation for TAG_PATH). This location can be changed to -# output / TRANSLATION[lang] / TAGS_INDEX_PATH -# with an arbitrary relative path TAGS_INDEX_PATH. -# (translatable) -# TAGS_INDEX_PATH = "tags.html" - -# If TAG_PAGES_ARE_INDEXES is set to True, each tag's page will contain -# the posts themselves. If set to False, it will be just a list of links. -# TAG_PAGES_ARE_INDEXES = False - -# Set descriptions for tag pages to make them more interesting. The -# default is no description. The value is used in the meta description -# and displayed underneath the tag list or index page’s title. -# TAG_DESCRIPTIONS = { -# DEFAULT_LANG: { -# "blogging": "Meta-blog posts about blogging about blogging.", -# }, -# } - -# Set special titles for tag pages. The default is "Posts about TAG". -# TAG_TITLES = { -# DEFAULT_LANG: { -# "blogging": "Meta-posts about blogging", -# "open source": "Posts about open source software" -# }, -# } - -# If you do not want to display a tag publicly, you can mark it as hidden. -# The tag will not be displayed on the tag list page, the tag cloud and posts. -# Tag pages will still be generated. -HIDDEN_TAGS = ["mathjax"] - -# Only include tags on the tag list/overview page if there are at least -# TAGLIST_MINIMUM_POSTS number of posts or more with every tag. Every tag -# page is still generated, linked from posts, and included in the sitemap. -# However, more obscure tags can be hidden from the tag index page. -# TAGLIST_MINIMUM_POSTS = 1 - -# A list of dictionaries specifying tags which translate to each other. -# Format: a list of dicts {language: translation, language2: translation2, …} -# For example: -# [ -# {'en': 'private', 'de': 'Privat'}, -# {'en': 'work', 'fr': 'travail', 'de': 'Arbeit'}, -# ] -# TAG_TRANSLATIONS = [] - -# If set to True, a tag in a language will be treated as a translation -# of the literally same tag in all other languages. Enable this if you -# do not translate tags, for example. -# TAG_TRANSLATIONS_ADD_DEFAULTS = True - -# Final locations are: -# output / TRANSLATION[lang] / CATEGORY_PATH / index.html (list of categories) -# output / TRANSLATION[lang] / CATEGORY_PATH / CATEGORY_PREFIX category.html (list of posts for a category) # NOQA: E501 -# output / TRANSLATION[lang] / CATEGORY_PATH / CATEGORY_PREFIX category RSS_EXTENSION (RSS feed for a category) # NOQA: E501 -# (translatable) -# CATEGORY_PATH = "categories" -# CATEGORY_PREFIX = "cat_" - -# By default, the list of categories is stored in -# output / TRANSLATION[lang] / CATEGORY_PATH / index.html -# (see explanation for CATEGORY_PATH). This location can be changed to -# output / TRANSLATION[lang] / CATEGORIES_INDEX_PATH -# with an arbitrary relative path CATEGORIES_INDEX_PATH. -# (translatable) -# CATEGORIES_INDEX_PATH = "categories.html" - -# If CATEGORY_ALLOW_HIERARCHIES is set to True, categories can be organized in -# hierarchies. For a post, the whole path in the hierarchy must be specified, -# using a forward slash ('/') to separate paths. Use a backslash ('\') to escape -# a forward slash or a backslash (i.e. '\//\\' is a path specifying the -# subcategory called '\' of the top-level category called '/'). -CATEGORY_ALLOW_HIERARCHIES = False -# If CATEGORY_OUTPUT_FLAT_HIERARCHY is set to True, the output written to output -# contains only the name of the leaf category and not the whole path. -CATEGORY_OUTPUT_FLAT_HIERARCHY = False - -# If CATEGORY_PAGES_ARE_INDEXES is set to True, each category's page will contain -# the posts themselves. If set to False, it will be just a list of links. -# CATEGORY_PAGES_ARE_INDEXES = False - -# Set descriptions for category pages to make them more interesting. The -# default is no description. The value is used in the meta description -# and displayed underneath the category list or index page’s title. -# CATEGORY_DESCRIPTIONS = { -# DEFAULT_LANG: { -# "blogging": "Meta-blog posts about blogging about blogging.", -# }, -# } - -# Set special titles for category pages. The default is "Posts about CATEGORY". -# CATEGORY_TITLES = { -# DEFAULT_LANG: { -# "blogging": "Meta-posts about blogging", -# "open source": "Posts about open source software" -# }, -# } - -# If you do not want to display a category publicly, you can mark it as hidden. -# The category will not be displayed on the category list page. -# Category pages will still be generated. -HIDDEN_CATEGORIES = [] - -# A list of dictionaries specifying categories which translate to each other. -# Format: a list of dicts {language: translation, language2: translation2, …} -# See TAG_TRANSLATIONS example above. -# CATEGORY_TRANSLATIONS = [] - -# If set to True, a category in a language will be treated as a translation -# of the literally same category in all other languages. Enable this if you -# do not translate categories, for example. -# CATEGORY_TRANSLATIONS_ADD_DEFAULTS = True - -# If no category is specified in a post, the destination path of the post -# can be used in its place. This replaces the sections feature. Using -# category hierarchies is recommended. -# CATEGORY_DESTPATH_AS_DEFAULT = False - -# If True, the prefix will be trimmed from the category name, eg. if the -# POSTS destination is "foo/bar", and the path is "foo/bar/baz/quux", -# the category will be "baz/quux" (or "baz" if only the first directory is considered). -# Note that prefixes coming from translations are always ignored. -# CATEGORY_DESTPATH_TRIM_PREFIX = False - -# If True, only the first directory of a path will be used. -# CATEGORY_DESTPATH_FIRST_DIRECTORY_ONLY = True - -# Map paths to prettier category names. (translatable) -# CATEGORY_DESTPATH_NAMES = { -# DEFAULT_LANG: { -# 'webdev': 'Web Development', -# 'webdev/django': 'Web Development/Django', -# 'random': 'Odds and Ends', -# }, -# } - -# By default, category indexes will appear in CATEGORY_PATH and use -# CATEGORY_PREFIX. If this is enabled, those settings will be ignored (except -# for the index) and instead, they will follow destination paths (eg. category -# 'foo' might appear in 'posts/foo'). If the category does not come from a -# destpath, first entry in POSTS followed by the category name will be used. -# For this setting, category hierarchies are required and cannot be flattened. -# CATEGORY_PAGES_FOLLOW_DESTPATH = False - -# If ENABLE_AUTHOR_PAGES is set to True and there is more than one -# author, author pages are generated. -# ENABLE_AUTHOR_PAGES = True - -# Path to author pages. Final locations are: -# output / TRANSLATION[lang] / AUTHOR_PATH / index.html (list of authors) -# output / TRANSLATION[lang] / AUTHOR_PATH / author.html (list of posts by an author) -# output / TRANSLATION[lang] / AUTHOR_PATH / author RSS_EXTENSION (RSS feed for an author) -# (translatable) -# AUTHOR_PATH = "authors" - -# If AUTHOR_PAGES_ARE_INDEXES is set to True, each author's page will contain -# the posts themselves. If set to False, it will be just a list of links. -# AUTHOR_PAGES_ARE_INDEXES = False - -# Set descriptions for author pages to make them more interesting. The -# default is no description. The value is used in the meta description -# and displayed underneath the author list or index page’s title. -# AUTHOR_PAGES_DESCRIPTIONS = { -# DEFAULT_LANG: { -# "Juanjo Conti": "Python coder and writer.", -# "Roberto Alsina": "Nikola father." -# }, -# } - - -# If you do not want to display an author publicly, you can mark it as hidden. -# The author will not be displayed on the author list page and posts. -# Tag pages will still be generated. -HIDDEN_AUTHORS = ["Guest"] - -# Final location for the main blog page and sibling paginated pages is -# output / TRANSLATION[lang] / INDEX_PATH / index-*.html -# (translatable) -INDEX_PATH = "blog" - -# Optional HTML that displayed on “main” blog index.html files. -# May be used for a greeting. (translatable) -FRONT_INDEX_HEADER = {DEFAULT_LANG: ""} - -# Create per-month archives instead of per-year -# CREATE_MONTHLY_ARCHIVE = False -# Create one large archive instead of per-year -# CREATE_SINGLE_ARCHIVE = False -# Create year, month, and day archives each with a (long) list of posts -# (overrides both CREATE_MONTHLY_ARCHIVE and CREATE_SINGLE_ARCHIVE) -# CREATE_FULL_ARCHIVES = False -# If monthly archives or full archives are created, adds also one archive per day -# CREATE_DAILY_ARCHIVE = False -# Create previous, up, next navigation links for archives -# CREATE_ARCHIVE_NAVIGATION = False -# Final locations for the archives are: -# output / TRANSLATION[lang] / ARCHIVE_PATH / ARCHIVE_FILENAME -# output / TRANSLATION[lang] / ARCHIVE_PATH / YEAR / index.html -# output / TRANSLATION[lang] / ARCHIVE_PATH / YEAR / MONTH / index.html -# output / TRANSLATION[lang] / ARCHIVE_PATH / YEAR / MONTH / DAY / index.html -# ARCHIVE_PATH = "" -# ARCHIVE_FILENAME = "archive.html" - -# If ARCHIVES_ARE_INDEXES is set to True, each archive page which contains a list -# of posts will contain the posts themselves. If set to False, it will be just a -# list of links. -# ARCHIVES_ARE_INDEXES = False - -# URLs to other posts/pages can take 3 forms: -# rel_path: a relative URL to the current page/post (default) -# full_path: a URL with the full path from the root -# absolute: a complete URL (that includes the SITE_URL) -# URL_TYPE = 'rel_path' - -# Extension for RSS feed files -# RSS_EXTENSION = ".xml" - -# RSS filename base (without extension); used for indexes and galleries. -# (translatable) -# RSS_FILENAME_BASE = "rss" - -# Final location for the blog main RSS feed is: -# output / TRANSLATION[lang] / RSS_PATH / RSS_FILENAME_BASE RSS_EXTENSION -# (translatable) -# RSS_PATH = "" - -# Final location for the blog main Atom feed is: -# output / TRANSLATION[lang] / ATOM_PATH / ATOM_FILENAME_BASE ATOM_EXTENSION -# (translatable) -# ATOM_PATH = "" - -# Atom filename base (without extension); used for indexes. -# (translatable) -ATOM_FILENAME_BASE = "feed" - -# Extension for Atom feed files -# ATOM_EXTENSION = ".atom" - -# Slug the Tag URL. Easier for users to type, special characters are -# often removed or replaced as well. -# SLUG_TAG_PATH = True - -# Slug the Author URL. Easier for users to type, special characters are -# often removed or replaced as well. -# SLUG_AUTHOR_PATH = True - -# A list of redirection tuples, [("foo/from.html", "/bar/to.html")]. -# -# A HTML file will be created in output/foo/from.html that redirects -# to the "/bar/to.html" URL. notice that the "from" side MUST be a -# relative URL. -# -# If you don't need any of these, just set to [] -REDIRECTIONS = [] - -# Presets of commands to execute to deploy. Can be anything, for -# example, you may use rsync: -# "rsync -rav --delete output/ joe@my.site:/srv/www/site" -# And then do a backup, or run `nikola ping` from the `ping` -# plugin (`nikola plugin -i ping`). Or run `nikola check -l`. -# You may also want to use github_deploy (see below). -# You can define multiple presets and specify them as arguments -# to `nikola deploy`. If no arguments are specified, a preset -# named `default` will be executed. You can use as many presets -# in a `nikola deploy` command as you like. -# DEPLOY_COMMANDS = { -# 'default': [ -# "rsync -rav --delete output/ joe@my.site:/srv/www/site", -# ] -# } - -# github_deploy configuration -# For more details, read the manual: -# https://getnikola.com/handbook.html#deploying-to-github -# You will need to configure the deployment branch on GitHub. -GITHUB_SOURCE_BRANCH = "src" -GITHUB_DEPLOY_BRANCH = "main" - -# The name of the remote where you wish to push to, using github_deploy. -GITHUB_REMOTE_NAME = "origin" - -# Whether or not github_deploy should commit to the source branch automatically -# before deploying. -GITHUB_COMMIT_SOURCE = True - -# Where the output site should be located -# If you don't use an absolute path, it will be considered as relative -# to the location of conf.py -OUTPUT_FOLDER = os.getenv("NIKOLA_OUTPUT_DIR", "output") - -# where the "cache" of partial generated content should be located -# default: 'cache' -# CACHE_FOLDER = 'cache' - -# Filters to apply to the output. -# A directory where the keys are either: a file extensions, or -# a tuple of file extensions. -# -# And the value is a list of commands to be applied in order. -# -# Each command must be either: -# -# A string containing a '%s' which will -# be replaced with a filename. The command *must* produce output -# in place. -# -# Or: -# -# A python callable, which will be called with the filename as -# argument. -# -# By default, only .php files uses filters to inject PHP into -# Nikola’s templates. All other filters must be enabled through FILTERS. -# -# Many filters are shipped with Nikola. A list is available in the manual: -# -# -from nikola import filters - -FILTERS = {".html": [filters.add_header_permalinks]} - -# Executable for the "yui_compressor" filter (defaults to 'yui-compressor'). -# YUI_COMPRESSOR_EXECUTABLE = 'yui-compressor' - -# Executable for the "closure_compiler" filter (defaults to 'closure-compiler'). -# CLOSURE_COMPILER_EXECUTABLE = 'closure-compiler' - -# Executable for the "optipng" filter (defaults to 'optipng'). -# OPTIPNG_EXECUTABLE = 'optipng' - -# Executable for the "jpegoptim" filter (defaults to 'jpegoptim'). -# JPEGOPTIM_EXECUTABLE = 'jpegoptim' - -# Executable for the "html_tidy_withconfig", "html_tidy_nowrap", -# "html_tidy_wrap", "html_tidy_wrap_attr" and "html_tidy_mini" filters -# (defaults to 'tidy5'). -# HTML_TIDY_EXECUTABLE = 'tidy5' - -# List of XPath expressions which should be used for finding headers -# ({hx} is replaced by headers h1 through h6). -# You must change this if you use a custom theme that does not use -# "e-content entry-content" as a class for post and page contents. -HEADER_PERMALINKS_XPATH_LIST = ['*//div[@class="e-content entry-content"]//{hx}'] -# Include *every* header (not recommended): -# HEADER_PERMALINKS_XPATH_LIST = ['*//{hx}'] - -# File blacklist for header permalinks. Contains output path -# (eg. 'output/index.html') -# HEADER_PERMALINKS_FILE_BLACKLIST = [] - -# Expert setting! Create a gzipped copy of each generated file. Cheap server- -# side optimization for very high traffic sites or low memory servers. -# GZIP_FILES = False -# File extensions that will be compressed -# GZIP_EXTENSIONS = ('.txt', '.htm', '.html', '.css', '.js', '.json', '.atom', '.xml') -# Use an external gzip command? None means no. -# Example: GZIP_COMMAND = "pigz -k {filename}" -# GZIP_COMMAND = None -# Make sure the server does not return a "Accept-Ranges: bytes" header for -# files compressed by this option! OR make sure that a ranged request does not -# return partial content of another representation for these resources. Do not -# use this feature if you do not understand what this means. - -# ############################################################################# -# Image Gallery Options -# ############################################################################# - -# One or more folders containing galleries. The format is a dictionary of -# {"source": "relative_destination"}, where galleries are looked for in -# "source/" and the results will be located in -# "OUTPUT_PATH/relative_destination/gallery_name" -# Default is: -# GALLERY_FOLDERS = {"galleries": "galleries"} -# More gallery options: -# THUMBNAIL_SIZE = 180 -# MAX_IMAGE_SIZE = 1280 -# USE_FILENAME_AS_TITLE = True -# EXTRA_IMAGE_EXTENSIONS = [] -# -# If set to False, it will sort by filename instead. Defaults to True -# GALLERY_SORT_BY_DATE = True - -# If set to True, EXIF data will be copied when an image is thumbnailed or -# resized. (See also EXIF_WHITELIST) -# PRESERVE_EXIF_DATA = False - -# If you have enabled PRESERVE_EXIF_DATA, this option lets you choose EXIF -# fields you want to keep in images. (See also PRESERVE_EXIF_DATA) -# -# For a full list of field names, please see here: -# http://www.cipa.jp/std/documents/e/DC-008-2012_E.pdf -# -# This is a dictionary of lists. Each key in the dictionary is the -# name of a IDF, and each list item is a field you want to preserve. -# If you have a IDF with only a '*' item, *EVERY* item in it will be -# preserved. If you don't want to preserve anything in a IDF, remove it -# from the setting. By default, no EXIF information is kept. -# Setting the whitelist to anything other than {} implies -# PRESERVE_EXIF_DATA is set to True -# To preserve ALL EXIF data, set EXIF_WHITELIST to {"*": "*"} - -# EXIF_WHITELIST = {} - -# Some examples of EXIF_WHITELIST settings: - -# Basic image information: -# EXIF_WHITELIST['0th'] = [ -# "Orientation", -# "XResolution", -# "YResolution", -# ] - -# If you want to keep GPS data in the images: -# EXIF_WHITELIST['GPS'] = ["*"] - -# Embedded thumbnail information: -# EXIF_WHITELIST['1st'] = ["*"] - -# If set to True, any ICC profile will be copied when an image is thumbnailed or -# resized. -# PRESERVE_ICC_PROFILES = False - -# Folders containing images to be used in normal posts or pages. -# IMAGE_FOLDERS is a dictionary of the form {"source": "destination"}, -# where "source" is the folder containing the images to be published, and -# "destination" is the folder under OUTPUT_PATH containing the images copied -# to the site. Thumbnail images will be created there as well. - -# To reference the images in your posts, include a leading slash in the path. -# For example, if IMAGE_FOLDERS = {'images': 'images'}, write -# -# .. image:: /images/tesla.jpg -# -# See the Nikola Handbook for details (in the “Embedding Images” and -# “Thumbnails” sections) - -# Images will be scaled down according to IMAGE_THUMBNAIL_SIZE and MAX_IMAGE_SIZE -# options, but will have to be referenced manually to be visible on the site -# (the thumbnail has ``.thumbnail`` added before the file extension by default, -# but a different naming template can be configured with IMAGE_THUMBNAIL_FORMAT). - -IMAGE_FOLDERS = {"images": "images"} -# IMAGE_THUMBNAIL_SIZE = 400 -# IMAGE_THUMBNAIL_FORMAT = '{name}.thumbnail{ext}' - -# ############################################################################# -# HTML fragments and diverse things that are used by the templates -# ############################################################################# - -# Data about post-per-page indexes. -# INDEXES_PAGES defaults to ' old posts, page %d' or ' page %d' (translated), -# depending on the value of INDEXES_PAGES_MAIN. -# -# (translatable) If the following is empty, defaults to BLOG_TITLE: -# INDEXES_TITLE = "" -# -# (translatable) If the following is empty, defaults to ' [old posts,] page %d' (see above): -# INDEXES_PAGES = "" -# -# If the following is True, INDEXES_PAGES is also displayed on the main (the -# newest) index page (index.html): -# INDEXES_PAGES_MAIN = False -# -# If the following is True, index-1.html has the oldest posts, index-2.html the -# second-oldest posts, etc., and index.html has the newest posts. This ensures -# that all posts on index-x.html will forever stay on that page, now matter how -# many new posts are added. -# If False, index-1.html has the second-newest posts, index-2.html the third-newest, -# and index-n.html the oldest posts. When this is active, old posts can be moved -# to other index pages when new posts are added. -# INDEXES_STATIC = True -# -# (translatable) If PRETTY_URLS is set to True, this setting will be used to create -# prettier URLs for index pages, such as page/2/index.html instead of index-2.html. -# Valid values for this settings are: -# * False, -# * a list or tuple, specifying the path to be generated, -# * a dictionary mapping languages to lists or tuples. -# Every list or tuple must consist of strings which are used to combine the path; -# for example: -# ['page', '{number}', '{index_file}'] -# The replacements -# {number} --> (logical) page number; -# {old_number} --> the page number inserted into index-n.html before (zero for -# the main page); -# {index_file} --> value of option INDEX_FILE -# are made. -# Note that in case INDEXES_PAGES_MAIN is set to True, a redirection will be created -# for the full URL with the page number of the main page to the normal (shorter) main -# page URL. -# INDEXES_PRETTY_PAGE_URL = False -# -# If the following is true, a page range navigation will be inserted to indices. -# Please note that this will undo the effect of INDEXES_STATIC, as all index pages -# must be recreated whenever the number of pages changes. -# SHOW_INDEX_PAGE_NAVIGATION = False - -# If the following is True, a meta name="generator" tag is added to pages. The -# generator tag is used to specify the software used to generate the page -# (it promotes Nikola). -# META_GENERATOR_TAG = True - -# Color scheme to be used for code blocks. If your theme provides -# "assets/css/code.css" this is ignored. Leave empty to disable. -# Can be any of: -# algol, algol_nu, autumn, borland, bw, colorful, default, emacs, friendly, -# fruity, igor, lovelace, manni, monokai, murphy, native, paraiso-dark, -# paraiso-light, pastie, perldoc, rrt, tango, trac, vim, vs, xcode -# This list MAY be incomplete since pygments adds styles every now and then. -# Check with list(pygments.styles.get_all_styles()) in an interpreter. -# CODE_COLOR_SCHEME = 'default' - -# FAVICONS contains (name, file, size) tuples. -# Used to create favicon link like this: -# -FAVICONS = ( - ("icon", "/assets/img/favicon.ico", "16x16"), - # ("icon", "/icon_128x128.png", "128x128"), -) - -# Show teasers (instead of full posts) in indexes? Defaults to False. -INDEX_TEASERS = True - -# HTML fragments with the Read more... links. -# The following tags exist and are replaced for you: -# {link} A link to the full post page. -# {read_more} The string “Read more” in the current language. -# {reading_time} An estimate of how long it will take to read the post. -# {remaining_reading_time} An estimate of how long it will take to read the post, sans the teaser. # NOQA: E501 -# {min_remaining_read} The string “{remaining_reading_time} min remaining to read” in the current language. # NOQA: E501 -# {paragraph_count} The amount of paragraphs in the post. -# {remaining_paragraph_count} The amount of paragraphs in the post, sans the teaser. -# {post_title} The title of the post. -# {{ A literal { (U+007B LEFT CURLY BRACKET) -# }} A literal } (U+007D RIGHT CURLY BRACKET) - -# 'Read more...' for the index page, if INDEX_TEASERS is True (translatable) -INDEX_READ_MORE_LINK = '

{read_more}…

' -# 'Read more...' for the feeds, if FEED_TEASERS is True (translatable) -FEED_READ_MORE_LINK = '

{read_more}… ({min_remaining_read})

' - -# Append a URL query to the FEED_READ_MORE_LINK in Atom and RSS feeds. Advanced -# option used for traffic source tracking. -# Minimum example for use with Piwik: "pk_campaign=feed" -# The following tags exist and are replaced for you: -# {feedRelUri} A relative link to the feed. -# {feedFormat} The name of the syndication format. -# Example using replacement for use with Google Analytics: -# "utm_source={feedRelUri}&utm_medium=nikola_feed&utm_campaign={feedFormat}_feed" -FEED_LINKS_APPEND_QUERY = False - -# A HTML fragment describing the license, for the sidebar. -# (translatable) -LICENSE = "" -# I recommend using the Creative Commons' wizard: -# https://creativecommons.org/choose/ -# LICENSE = """ -# -# Creative Commons License BY-NC-SA""" - -# A small copyright notice for the page footer (in HTML). -# (translatable) -CONTENT_FOOTER = 'Contents © {date} {author} - Powered by Nikola {license}' # NOQA: E501 - -# Things that will be passed to CONTENT_FOOTER.format(). This is done -# for translatability, as dicts are not formattable. Nikola will -# intelligently format the setting properly. -# The setting takes a dict. The keys are languages. The values are -# tuples of tuples of positional arguments and dicts of keyword arguments -# to format(). For example, {'en': (('Hello'), {'target': 'World'})} -# results in CONTENT_FOOTER['en'].format('Hello', target='World'). -# If you need to use the literal braces '{' and '}' in your footer text, use -# '{{' and '}}' to escape them (str.format is used) -# WARNING: If you do not use multiple languages with CONTENT_FOOTER, this -# still needs to be a dict of this format. (it can be empty if you -# do not need formatting) -# (translatable) -CONTENT_FOOTER_FORMATS = { - DEFAULT_LANG: ( - (), - { - "email": BLOG_EMAIL, - "author": BLOG_AUTHOR, - "date": time.gmtime().tm_year, - "license": LICENSE, - }, - ) -} - -# A simple copyright tag for inclusion in RSS feeds that works just -# like CONTENT_FOOTER and CONTENT_FOOTER_FORMATS -RSS_COPYRIGHT = 'Contents © {date} {author} {license}' -RSS_COPYRIGHT_PLAIN = "Contents © {date} {author} {license}" -RSS_COPYRIGHT_FORMATS = CONTENT_FOOTER_FORMATS - -# To use comments, you can choose between different third party comment -# systems. The following comment systems are supported by Nikola: -# disqus, facebook, intensedebate, isso, livefyre, muut -# You can leave this option blank to disable comments. -COMMENT_SYSTEM = "" -# And you also need to add your COMMENT_SYSTEM_ID which -# depends on what comment system you use. The default is -# "nikolademo" which is a test account for Disqus. More information -# is in the manual. -COMMENT_SYSTEM_ID = "" - -# Create index.html for page folders? -# WARNING: if a page would conflict with the index file (usually -# caused by setting slug to `index`), the PAGE_INDEX -# will not be generated for that directory. -# PAGE_INDEX = False -# Enable comments on pages (i.e. not posts)? -# COMMENTS_IN_PAGES = False -# Enable comments on picture gallery pages? -# COMMENTS_IN_GALLERIES = False - -# What file should be used for directory indexes? -# Defaults to index.html -# Common other alternatives: default.html for IIS, index.php -# INDEX_FILE = "index.html" - -# If a link ends in /index.html, drop the index.html part. -# http://mysite/foo/bar/index.html => http://mysite/foo/bar/ -# (Uses the INDEX_FILE setting, so if that is, say, default.html, -# it will instead /foo/default.html => /foo) -STRIP_INDEXES = True - -# List of files relative to the server root (!) that will be asked to be excluded -# from indexing and other robotic spidering. * is supported. Will only be effective -# if SITE_URL points to server root. The list is used to exclude resources from -# /robots.txt and /sitemap.xml, and to inform search engines about /sitemapindex.xml. -# ROBOTS_EXCLUSIONS = ["/archive.html", "/category/*.html"] - -# Instead of putting files in .html, put them in /index.html. -# No web server configuration is required. Also enables STRIP_INDEXES. -# This can be disabled on a per-page/post basis by adding -# .. pretty_url: False -# to the metadata. -PRETTY_URLS = False - -# If True, publish future dated posts right away instead of scheduling them. -# Defaults to False. -# FUTURE_IS_NOW = False - -# If True, future dated posts are allowed in deployed output -# Only the individual posts are published/deployed; not in indexes/sitemap -# Generally, you want FUTURE_IS_NOW and DEPLOY_FUTURE to be the same value. -# DEPLOY_FUTURE = False -# If False, draft posts will not be deployed -# DEPLOY_DRAFTS = True - -# Allows scheduling of posts using the rule specified here (new_post -s) -# Specify an iCal Recurrence Rule: http://www.kanzaki.com/docs/ical/rrule.html -# SCHEDULE_RULE = '' -# If True, use the scheduling rule to all posts (not pages!) by default -# SCHEDULE_ALL = False - -# What Markdown extensions to enable? -# You will also get gist, nikola and podcast because those are -# done in the code, hope you don't mind ;-) -# Note: most Nikola-specific extensions are done via the Nikola plugin system, -# with the MarkdownExtension class and should not be added here. -# The default is ['fenced_code', 'codehilite'] -MARKDOWN_EXTENSIONS = [ - "markdown.extensions.fenced_code", - "markdown.extensions.codehilite", - "markdown.extensions.extra", - "pymdownx.magiclink", -] - -# Options to be passed to markdown extensions (See https://python-markdown.github.io/reference/) -# Default is {} (no config at all) -MARKDOWN_EXTENSION_CONFIGS = { - DEFAULT_LANG: { - "pymdownx.magiclink": { - "hide_protocol": True, - "repo_url_shortener": True, - "repo_url_shorthand": True, - "provider": "github", - "user": "Cantera", - "repo": "cantera", - } - } -} - - -# Extra options to pass to the pandoc command. -# by default, it's empty, is a list of strings, for example -# ['-F', 'pandoc-citeproc', '--bibliography=/Users/foo/references.bib'] -# Pandoc does not demote headers by default. To enable this, you can use, for example -# ['--base-header-level=2'] -# PANDOC_OPTIONS = [] - -# Social buttons. This is sample code for AddThis (which was the default for a -# long time). Insert anything you want here, or even make it empty (which is -# the default right now) -# (translatable) -# SOCIAL_BUTTONS_CODE = """ -# """ - -# Show link to source for the posts? -SHOW_SOURCELINK = False -# Copy the source files for your pages? -# Setting it to False implies SHOW_SOURCELINK = False -# COPY_SOURCES = True - -# Modify the number of Post per Index Page -# Defaults to 10 -# INDEX_DISPLAY_POST_COUNT = 10 - -# By default, Nikola generates RSS files for the website and for tags, and -# links to it. Set this to False to disable everything RSS-related. -# GENERATE_RSS = True - -# By default, Nikola does not generates Atom files for indexes and links to -# them. Generate Atom for tags by setting TAG_PAGES_ARE_INDEXES to True. -# Atom feeds are built based on INDEX_DISPLAY_POST_COUNT and not FEED_LENGTH -# Switch between plain-text summaries and full HTML content using the -# FEED_TEASER option. FEED_LINKS_APPEND_QUERY is also respected. Atom feeds -# are generated even for old indexes and have pagination link relations -# between each other. Old Atom feeds with no changes are marked as archived. -# GENERATE_ATOM = False - -# Only include teasers in Atom and RSS feeds. Disabling include the full -# content. Defaults to True. -# FEED_TEASERS = True - -# Strip HTML from Atom and RSS feed summaries and content. Defaults to False. -# FEED_PLAIN = False - -# Number of posts in Atom and RSS feeds. -# FEED_LENGTH = 10 - -# RSS_LINK is a HTML fragment to link the RSS or Atom feeds. If set to None, -# the base.tmpl will use the feed Nikola generates. However, you may want to -# change it for a FeedBurner feed or something else. -# RSS_LINK = None - -# A search form to search this site, for the sidebar. You can use a Google -# custom search (https://www.google.com/cse/) -# Or a DuckDuckGo search: https://duckduckgo.com/search_box.html -# Default is no search form. -# (translatable) -# SEARCH_FORM = "" -# -# This search form works for any site and looks good in the "site" theme where -# it appears on the navigation bar: -# -# SEARCH_FORM = """ -# -# -# -# """ % SITE_URL -# -# If you prefer a Google search form, here's an example that should just work: -# SEARCH_FORM = """ -# -# -# -# """ % SITE_URL - -# Use content distribution networks for jQuery, twitter-bootstrap css and js, -# and html5shiv (for older versions of Internet Explorer) -# If this is True, jQuery and html5shiv are served from the Google CDN and -# Bootstrap is served from BootstrapCDN (provided by MaxCDN) -# Set this to False if you want to host your site without requiring access to -# external resources. -USE_CDN = True - -# Check for USE_CDN compatibility. -# If you are using custom themes, have configured the CSS properly and are -# receiving warnings about incompatibility but believe they are incorrect, you -# can set this to False. -USE_CDN_WARNING = False - -# Extra things you want in the pages HEAD tag. This will be added right -# before -# (translatable) -# EXTRA_HEAD_DATA = "" -# Google Analytics or whatever else you use. Added to the bottom of -# in the default template (base.tmpl). -# (translatable) -# BODY_END = "" - -# The possibility to extract metadata from the filename by using a -# regular expression. -# To make it work you need to name parts of your regular expression. -# The following names will be used to extract metadata: -# - title -# - slug -# - date -# - tags -# - link -# - description -# -# An example re is the following: -# '.*\/(?P\d{4}-\d{2}-\d{2})-(?P.*)-(?P.*)\.rst' -# (Note the '.*\/' in the beginning -- matches source paths relative to conf.py) -# FILE_METADATA_REGEXP = None - -# Should titles fetched from file metadata be unslugified (made prettier?) -# FILE_METADATA_UNSLUGIFY_TITLES = True - -# If enabled, extract metadata from docinfo fields in reST documents -# USE_REST_DOCINFO_METADATA = False - -# If enabled, hide docinfo fields in reST document output -# HIDE_REST_DOCINFO = False - -# Map metadata from other formats to Nikola names. -# Supported formats: yaml, toml, rest_docinfo, markdown_metadata -# METADATA_MAPPING = {} -# -# Example for Pelican compatibility: -# METADATA_MAPPING = { -# "rest_docinfo": {"summary": "description", "modified": "updated"}, -# "markdown_metadata": {"summary": "description", "modified": "updated"} -# } -# Other examples: https://getnikola.com/handbook.html#mapping-metadata-from-other-formats - -# Map metadata between types/values. (Runs after METADATA_MAPPING.) -# Supported formats: nikola, yaml, toml, rest_docinfo, markdown_metadata -# The value on the right should be a dict of callables. -# METADATA_VALUE_MAPPING = {} -# Examples: -# METADATA_VALUE_MAPPING = { -# "yaml": {"keywords": lambda value: ', '.join(value)}, # yaml: 'keywords' list -> str -# "nikola": { -# "widgets": lambda value: value.split(', '), # nikola: 'widgets' comma-separated string -> list # NOQA: E501 -# "tags": str.lower # nikola: force lowercase 'tags' (input would be string) -# } -# } - -# Additional metadata that is added to a post when creating a new_post -# ADDITIONAL_METADATA = {} - -# Nikola supports Twitter Card summaries, but they are disabled by default. -# They make it possible for you to attach media to Tweets that link -# to your content. -# -# IMPORTANT: -# Please note, that you need to opt-in for using Twitter Cards! -# To do this please visit https://cards-dev.twitter.com/validator -# -# Uncomment and modify to following lines to match your accounts. -# Images displayed come from the `previewimage` meta tag. -# You can specify the card type by using the `card` parameter in TWITTER_CARD. -# TWITTER_CARD = { -# # 'use_twitter_cards': True, # enable Twitter Cards -# # 'card': 'summary', # Card type, you can also use 'summary_large_image', -# # see https://dev.twitter.com/cards/types -# # 'site': '@website', # twitter nick for the website -# # 'creator': '@username', # Username for the content creator / author. -# } - -# If webassets is installed, bundle JS and CSS into single files to make -# site loading faster in a HTTP/1.1 environment but is not recommended for -# HTTP/2.0 when caching is used. Defaults to True. -USE_BUNDLES = False - -# Plugins you don't want to use. Be careful :-) -DISABLED_PLUGINS = [ - "render_archive", - "classify_archive", - "render_galleries", - "render_listings", -] - -# Special settings to disable only parts of the indexes plugin. -# Use with care. -# DISABLE_INDEXES = False -# DISABLE_MAIN_ATOM_FEED = False -# DISABLE_MAIN_RSS_FEED = False - -# Add the absolute paths to directories containing plugins to use them. -# For example, the `plugins` directory of your clone of the Nikola plugins -# repository. -# EXTRA_PLUGINS_DIRS = [] - -# Add the absolute paths to directories containing themes to use them. -# For example, the `v7` directory of your clone of the Nikola themes -# repository. -# EXTRA_THEMES_DIRS = [] - -# List of regular expressions, links matching them will always be considered -# valid by "nikola check -l" -# LINK_CHECK_WHITELIST = [] - -# If set to True, enable optional hyphenation in your posts (requires pyphen) -# Enabling hyphenation has been shown to break math support in some cases, -# use with caution. -# HYPHENATE = False - -# The <hN> tags in HTML generated by certain compilers (reST/Markdown) -# will be demoted by that much (1 → h1 will become h2 and so on) -# This was a hidden feature of the Markdown and reST compilers in the -# past. Useful especially if your post titles are in <h1> tags too, for -# example. -# (defaults to 1.) -# DEMOTE_HEADERS = 1 - -# Docutils, by default, will perform a transform in your documents -# extracting unique titles at the top of your document and turning -# them into metadata. This surprises a lot of people, and setting -# this option to True will prevent it. -# NO_DOCUTILS_TITLE_TRANSFORM = False - -# If you don’t like slugified file names ([a-z0-9] and a literal dash), -# and would prefer to use all the characters your file system allows. -# USE WITH CARE! This is also not guaranteed to be perfect, and may -# sometimes crash Nikola, your web server, or eat your cat. -# USE_SLUGIFY = True - -# If set to True, the tags 'draft', 'mathjax' and 'private' have special -# meaning. If set to False, these tags are handled like regular tags. -USE_TAG_METADATA = False - -# If set to True, a warning is issued if one of the 'draft', 'mathjax' -# and 'private' tags are found in a post. Useful for checking that -# migration was successful. -WARN_ABOUT_TAG_METADATA = False - -# Templates will use those filters, along with the defaults. -# Consult your engine's documentation on filters if you need help defining -# those. -# TEMPLATE_FILTERS = {} - -# Put in global_context things you want available on all your templates. -# It can be anything, data, functions, modules, etc. -GLOBAL_CONTEXT = {} - -# Add functions here and they will be called with template -# GLOBAL_CONTEXT as parameter when the template is about to be -# rendered -GLOBAL_CONTEXT_FILLER = [] diff --git a/make.bat b/make.bat new file mode 100644 index 000000000..747ffb7b3 --- /dev/null +++ b/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/pages/affiliated.rst b/pages/affiliated.rst deleted file mode 100644 index 36bc3fdd0..000000000 --- a/pages/affiliated.rst +++ /dev/null @@ -1,135 +0,0 @@ -.. title: Affiliated Packages -.. description: Packages in the Cantera ecosystem -.. slug: affiliated-packages - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Affiliated Packages</h1> - - .. class:: lead - - Packages in the Cantera ecosystem - -While Cantera provides some standalone models and applications, numerous external packages -exist that provide more specialized functionality and rely on Cantera. Here we provide a -non-exhaustive, alphabetical, list of these packages; if you would like us to include your package, please -`submit a pull request <https://github.com/cantera/cantera-website/pulls>`__, -`file an issue <https://github.com/cantera/cantera-website/issues/new>`__, or -post on the `Google Users' Group <https://groups.google.com/g/cantera-users>`__. - ------------- - -**Arrhenius.jl**: differential combustion modeling software in Julia. - -| `Repository <https://github.com/DENG-MIT/Arrhenius.jl>`__ -| Maintainer(s): Weiqi Ji - ------------- - -**ASALI**: graphical user interface for calculating properties using Cantera. - -| `Repository <https://github.com/srebughini/ASALI>`__ -| Maintainer(s): Stefano Rebughini - ------------- - -**BIOVIA Materials Studio**: commercial modeling and simulation software for materials science and chemistry. - -| `Website <https://www.3ds.com/products-services/biovia/products/molecular-modeling-simulation/biovia-materials-studio/>`__ - ------------- - -**CollectionOfMechanisms**: a hub for combustion reaction mechanisms including converted Cantera XML and YAML based mechanisms. - -| `Repository <https://github.com/jiweiqi/CollectionOfMechanisms>`__ -| Maintainer(s): Weiqi Ji, Jeff Santner - ------------- - -**ctwrap**: a light-weight Python wrapper facilitating batch simulations. - -| `Website <https://microcombustion.github.io/ctwrap/>`__ -| `Repository <https://github.com/microcombustion/ctwrap>`__ -| Maintainer(s): Ingmar Schoegl - ------------- - -**Ember**: a quasi-one-dimensional, unsteady reacting flow solver that can simulate a number of fundamental flame configurations: premixed laminar flames, opposed-flow strained flames (premixed or diffusion), axisymmetric (tubular) flames with positive or negative curvature, and steady 2D flames in a prescribed velocity field. - -| `Repository <https://github.com/speth/ember>`__ -| Maintainer(s): `Ray Speth <https://github.com/speth>`__ - ------------- - -**Frhodo**: a GUI-based application for simulating experimental data and optimizing chemical kinetics mechanisms. - -| `Repository <https://github.com/Argonne-National-Laboratory/Frhodo>`__ -| Maintainer(s): Travis Sikes, Robert Tranter - ------------- - -**gas-properties**: a python GUI for calculating properties of gases, equilibrium states, and isentropic compression. Similar to unsupported GasEQ software. - -| `Repository <https://github.com/jsantner/gas-properties>`__ -| Maintainer(s): Jeff Santner - ------------- - -**PoKITT**: a library for Portable Kinetics, Thermodynamics, and Transport calculations. - -| `Repository <https://gitlab.multiscale.utah.edu/common/PoKiTT>`__ -| Maintainer(s): James Sutherland - ------------- - -**pyJac**: generates C and CUDA source code for analytically calculating the Jacobian matrix for a chemical kinetic model, along with species and reaction rates. - -| `Website <http://slackha.github.io/pyJac/>`__ -| `Repository <https://github.com/SLACKHA/pyJac>`__ -| Maintainer(s): Nick Curtis, Kyle Niemeyer - ------------- - -**pyMARS**: Python-based (chemical kinetic) Model Automatic Reduction Software (pyMARS) implements multiple techniques for reducing the size and complexity of detailed chemical kinetic models. - -| `Repository <https://github.com/Niemeyer-Research-Group/pyMARS>`__ -| Maintainer(s): Phillip Mestas, Kyle Niemeyer - ------------- - -**reactorch**: A Differentiable Reacting Flow Simulation Package in PyTorch. - -| `Repository <https://github.com/DENG-MIT/reactorch>`__ -| Maintainer(s): Weiqi Ji - ------------- - -**RGFROSH**: A Python real and ideal gas frozen shock solver. - -| `Website <https://VasuLab.github.io/RGFROSH>`__ -| `Repository <https://github.com/VasuLab/RGFROSH>`__ -| Maintainer(s): Cory Kinney - ------------- - -**RMG**: Reaction Mechanism Generator, a tool for automatically generating chemical reaction mechanisms for modeling reaction systems including pyrolysis, combustion, atmospheric science, and more. - -| `Website <https://rmg.mit.edu>`__ -| `Repository <https://github.com/ReactionMechanismGenerator/RMG-Py>`__ -| Maintainer(s): William Green, Richard West - ------------- - -**SDToolbox**: the Shock & Detonation Toolbox enables the solution of standard problems for gas-phase explosions using realistic thermochemistry and detailed chemical kinetics. - -| `Website <http://shepherd.caltech.edu/EDL/PublicResources/sdt/>`__ -| Maintainer(s): Joseph E. Shepherd - ------------- - -**ChemCheck**: A tool to help Cantera users to detect chemical and syntax errors in kinetic models - -| `Repository <https://github.com/comocheng/ChemCheck>`__ -| Maintainer(s): Chao Xu, Richard West diff --git a/pages/community.rst b/pages/community.rst deleted file mode 100644 index 2b0bf485e..000000000 --- a/pages/community.rst +++ /dev/null @@ -1,209 +0,0 @@ -.. title: Community -.. description: All about the Cantera community and how to contribute -.. slug: community - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">The Cantera Community</h1> - - .. class:: lead - - Resources to help you participate in the community of Cantera users and developers - -.. contents:: :depth: 2 - -About the Cantera Community ---------------------------- - -Cantera was originally developed by :doc:`Prof. David G. Goodwin <dave>` at the California -Institute of Technology. Building on Prof. Goodwin's legacy, Cantera is licensed -under a `permissive 3-Clause BSD license -<https://github.com/Cantera/cantera/blob/main/License.txt>`__, ensuring that the -software will remain open source and available for all to use. - -In this vein, Cantera software relies exclusively upon the volunteer -contributions of its users. These contributions range from diagnosing and -reporting problems/bugs, to helping others learn to use Cantera, to developing -and implementing new software capabilities. - -While Cantera provides some standalone models and applications, numerous external -packages exist that provide more specialized functionality and rely on Cantera. We -provide a non-exhaustive list of these :doc:`affiliated packages <affiliated-packages>`. - -Governance -~~~~~~~~~~ - -Cantera is governed by a Steering Committee; more information about our project's -governance policies can be found on the :doc:`governance <governance>` page. - - -The Cantera Users' Group -~~~~~~~~~~~~~~~~~~~~~~~~ - -The `Cantera Users’ Group -<https://groups.google.com/g/cantera-users>`__ on Google Groups is -the forum where most Cantera users have their questions asked and answered. If -you need help using Cantera and cannot find an answer in the tutorials or -documentation at Cantera's website, consider joining and asking a question -there. A few notes: - -* Please use the search feature before posting to see if your question has been - answered before. -* If you are not running the current stable release of Cantera, please upgrade - first, and see if the problem persists. -* This group is moderated, so it may take some time for your posts to appear if - you are a new member. - -For installation/compilation problems, please provide: - -* The contents of the ``cantera.conf`` and ``config.log`` files, and the output of the ``scons - build`` and ``scons build dump`` commands. You can direct this output to a file - called ``buildlog.txt`` by running:: - - scons build >buildlog.txt 2>&1 - -* The exact version of Cantera you are trying to compile, and how it was - obtained (for example, downloaded source tarball or the specific Git commit). -* Your operating system, compiler versions, and the versions of any other - relevant software. - -For application problems (that is, not related to installation or compilation), -please: - -* Provide a minimal, complete, and verifiable example that demonstrates - the problem when making your post; in short this means include a code example - and input files. -* Please also provide information about your operating system and Cantera - version. This will enable other members of the group to efficiently - understand the problem and offer suggestions on how to fix it. -* Please DO NOT post screenshots of code or error messages! They cannot be - searched by anyone looking to solve a similar problem, and also cannot be - read by text readers for visually impaired users. Instead, please copy and - paste any relevant text directly into your message. Thanks! - - -Interacting with the Cantera Community --------------------------------------- - -Code of Conduct -~~~~~~~~~~~~~~~ - -All online and in-person interactions and communications related to Cantera are -governed by the `Cantera Code of Conduct -<https://github.com/Cantera/cantera/blob/main/CODE_OF_CONDUCT.md>`__. This code -of conduct sets expectations for the community to ensure that users and -contributors are able to participate in a respectful and welcoming environment. - -Please adhere to this code of conduct in any interactions you have in the Cantera -community. It is strictly enforced on all official Cantera repositories, websites, -users' group, and other resources. If you encounter someone violating these terms, -please `contact the code of conduct team <mailto:conduct@cantera.org>`__ -(`@speth <https://github.com/speth>`__, -`@bryanwweber <https://github.com/bryanwweber>`__, and -`@kyleniemeyer <https://github.com/kyleniemeyer>`__) and we will address it as -soon as possible. - -Contributing Code -~~~~~~~~~~~~~~~~~ - -If there is a feature you would like to see added to Cantera, please consider -becoming part of the developer community and contributing code! -`Cantera's code repository <https://github.com/Cantera/cantera>`__ is developed -openly on `GitHub <https://github.com/>`__. Contributions are welcomed from -anyone in the community; please see the `Contributors' guide -<https://github.com/Cantera/cantera/blob/main/CONTRIBUTING.md>`__ for -assistance in getting started. There are also plenty of current contributors -who are happy to help, if you do not know how to get started. - -Bug Reporting -~~~~~~~~~~~~~ - -**What should I do if I think I've found a bug in Cantera?** - -- Check to see if you're using the most recent version of Cantera, and - upgrade if not. -- Check the `Issue Tracker - <https://github.com/Cantera/cantera/issues>`__ to see if the issue - has already been reported. -- Try to generate a `minimal, complete, and verifiable example - <https://stackoverflow.com/help/mcve>`__ that demonstrates the observed bug. -- Create a new issue on the tracker (the "New Issue" button is toward the - upper right-hand corner, just above the list of open issues). Include as - much information as possible about your system configuration (operating - system, compiler versions, Python versions, installation method, etc.) - -**What information should I include in my bug report?** - -- The version of Cantera are you using, and how you installed it -- The operating system you are using -- If you compiled Cantera, what compiler you used, and what compilation - options you specified -- The version of Python or Matlab are you using, if applicable -- The necessary *input* to generate the reported behavior -- The full text of any error message you receive - -Supporting Cantera ------------------- - -Citing Cantera -~~~~~~~~~~~~~~ - -If you use Cantera in a publication, we would appreciate if you cited the -version of Cantera that you used. This helps to improve the reproducibility of -your work, as well as giving credit to the many `authors -<https://github.com/Cantera/cantera/blob/main/AUTHORS>`__ who have contributed -their time to developing Cantera. The recommended citation for Cantera is as -follows: - - David G. Goodwin, Harry K. Moffat, Ingmar Schoegl, Raymond L. Speth, and Bryan W. - Weber. *Cantera: An object-oriented software toolkit for chemical kinetics, - thermodynamics, and transport processes*. https://www.cantera.org, - 2023. Version 3.0.0. doi:10.5281/zenodo.8137090 - -The following BibTeX entry may also be used: - -.. code:: bibtex - - @misc{cantera, - author = "David G. Goodwin and Harry K. Moffat and Ingmar Schoegl and Raymond L. - Speth and Bryan W. Weber", - title = "Cantera: An Object-oriented Software Toolkit for Chemical - Kinetics, Thermodynamics, and Transport Processes", - year = 2023, - note = "Version 3.0.0", - howpublished = "\url{https://www.cantera.org}", - doi = {10.5281/zenodo.8137090} - } - -If you are using a different version of Cantera, update the ``year``, ``note`` -and ``doi`` fields accordingly. You can find the correct DOI for other versions -of Cantera in `Cantera's Zenodo Entry <https://doi.org/10.5281/zenodo.742000>`__. - -Donations -~~~~~~~~~ - -Finally, please consider financially supporting Cantera's development! Cantera -is a fiscally sponsored project of NumFOCUS, a 501(c)3 nonprofit dedicated to -supporting the open source scientific computing community. If you have found -Cantera to be useful to your research or company, please consider making a -`donation <https://numfocus.org/donate-to-cantera>`__ -to support our efforts. All donations will be used exclusively to fund the -development of Cantera's source code, documentation, or community. - -.. image:: /assets/img/SponsoredProject.png - :alt: Powered by NumFOCUS - :target: https://numfocus.org - :align: center - :width: 250px - -.. container:: text-center - - .. container:: btn btn-primary - :tagname: a - :attributes: href=https://numfocus.org/donate-to-cantera - title="Donate to Cantera" - rel=nofollow - - Donate to Cantera diff --git a/pages/compiling/compilation-reqs.rst b/pages/compiling/compilation-reqs.rst deleted file mode 100644 index 592cac0e5..000000000 --- a/pages/compiling/compilation-reqs.rst +++ /dev/null @@ -1,593 +0,0 @@ -.. title: Compilation Requirements - -.. _sec-compilation-reqs: - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4"> Compilation Requirements</h1> - - .. class:: lead - - Click the buttons below to see the required software that you must install to - compile Cantera on your operating system. - - .. raw:: html - - <div class="container"> - <div class="row"> - <div class="col"> - <a class="btn btn-secondary btn-block" href="#sec-conda">Conda</a> - </div> - <div class="col"> - <a class="btn btn-secondary btn-block" href="#sec-ubuntu-debian-reqs">Ubuntu & Debian</a> - </div> - <div class="col"> - <a class="btn btn-secondary btn-block" href="#sec-fedora-reqs">Fedora & RHEL</a> - </div> - <div class="col"> - <a class="btn btn-secondary btn-block" href="#sec-opensuse-reqs">OpenSUSE & SLE</a> - </div> - <div class="col"> - <a class="btn btn-secondary btn-block" href="#sec-windows">Windows</a> - </div> - <div class="col"> - <a class="btn btn-secondary btn-block" href="#sec-macos">macOS</a> - </div> - </div> - </div> - - -.. _sec-conda: - -Conda & Anaconda ----------------- - -General Notes -^^^^^^^^^^^^^ - -* These instructions will set you up to build Cantera with the dependencies installed in a Conda - environment - -* You will need to install compilers for your system by following the instructions in the sections - below to install the compiler for your operating system. - -* By default, Cantera is installed into the active conda environment, where the - layout of the directory structure corresponds to the - `configuration option <https://cantera.org/compiling/configure-build.html>`__ - ``layout=conda``. - -.. _sec-conda-reqs: - -Conda Requirements -^^^^^^^^^^^^^^^^^^ - -* Install `Anaconda <https://www.anaconda.com/download/>`__, - `Miniconda <https://conda.io/miniconda.html>`__, or - `Miniforge <https://github.com/conda-forge/miniforge>`__. - -* Launch the command line interface: - - * On macOS and Linux, the installer should add the appropriate activation mechanism - for your normal terminal by default. You can test this by running - - .. code:: bash - - conda --version - - in the terminal. If there is no output or an error appears, locate your Conda - installation and run the following code in the terminal: - - .. code:: bash - - /path/to/conda/install/folder/bin/conda init --all - - Then restart your terminal or shell. - - * On Windows, use the Anaconda PowerShell to run the build process (available from - the Start Menu). When using MSVC compilers, you also need to set environment - variables for x64-native tools (see `Developer command file locations - <https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=msvc-170#developer_command_file_locations>`__) - by running - - .. code:: bash - - . "C:\path\to\MSVC\Auxiliary\Build\vcvars64.bat" - - (note that the period ``'.'`` is part of the command). The path can be found as - follows: locate the **x64 Native Tools Command Prompt** in the Start Menu, - right-click, select **More > Open File Location**, right-click on the shortcut, - select **Properties** and copy the **Target** command. - -* Create an environment ``ct-build`` with the dependencies to build Cantera. Create a - file called ``environment.yaml`` with the following content - - .. code:: yaml - - name: ct-build - channels: - - conda-forge - dependencies: - - python # Cantera supports Python 3.8 and up - - scons # build system - - boost-cpp # C++ dependency - - hdf5 # optional C++ dependency - # - highfive # C++ dependency; uncomment to override Cantera default - # - sundials # uncomment to override Cantera default - # - fmt # uncomment to override Cantera default - # - eigen # uncomment to override Cantera default - # - yaml-cpp # uncomment to override Cantera default - # - libgomp # optional (OpenMP implementation when using GCC) - - cython # needed to build Python package - - numpy # needed to build Python package - - pip # needed to build Python package - - wheel # needed to build Python package - - setuptools # needed to build Python package - - pytest # needed for the Python test suite - # - pytest-cov # optional (needed if running with test coverage enabled) - - ruamel.yaml # needed for converter scripts - # - pandas # optional (needed for pandas interface) - # - scipy # optional (needed for some examples) - # - matplotlib # optional (needed for plots) - # - python-graphviz # optional (needed for reaction path diagrams) - - ipython # optional (needed for nicer interactive command line) - # - jupyter # optional (needed for Jupyter Notebook) - # - sphinx # optional (needed for documentation) - # - pydata-sphinx-theme # optional (needed for documentation) - # - sphinx-argparse # optional (needed for documentation) - # - doxygen # optional (needed for documentation) - # - graphviz # optional (needed for documentation) - # - texlive-core # optional (needed for documentation) - # - perl # optional (needed for documentation) - # - pip: # optional (list of PyPI managed packages) - # - sphinxcontrib-matlabdomain # optional (needed for documentation) - # - sphinxcontrib-doxylink # optional (needed for documentation) - - The environment is then created and activated using - - .. code:: bash - - conda env create -f environment.yaml - conda activate ct-build - - After creating the environment, it can be updated from within ``ct-build`` using - - .. code:: bash - - conda env update -f environment.yaml --prune - -* (Optional) If you want to override external libraries packaged with Cantera - (``sundials``, ``fmt``, ``eigen``, ``yaml-cpp``), simply uncomment corresponding - lines in the file ``environment.yaml`` above. Note that specific versions can be - forced by providing version numbers (example: replace ``sundials`` by - ``sundials=5.8`` to install version ``5.8``). - -* (Optional) If you want to build the documentation, make sure to uncomment lines for - ``pip``, ``sphinx``, ``doxygen``, and any other lines marked as "needed for - documentation" in the ``environment.yaml`` sample above. - -* (Cantera < 2.6 only) On previous Cantera versions, the build process required - configuration options ``boost_inc_dir`` and ``prefix`` (see - `configuration options <https://cantera.org/compiling/configure-build.html>`__); - starting with Cantera 2.6, these settings are detected automatically. - -.. note:: - - As the compiled code is based on the conda environment ``ct-build``, it is only - usable from within that environment. This means that in order to use the compiled - Cantera package, you have to activate your ``ct-build`` environment first. - -.. container:: container - - .. container:: row - - .. container:: col-12 text-right - - .. container:: btn btn-primary - :tagname: a - :attributes: href=source-code.html - - Next: Download the Source Code - -.. _sec-linux: - -Linux ------ - -General Notes -^^^^^^^^^^^^^ - -* To download the source code, installing ``git`` is highly recommended in addition - to the requirements listed below. - -* The following instructions use the system-installed versions of Python, but - alternate installations such as the Anaconda distribution of Python can be - used as well. - -* Cython is only required to be installed for the version of Python that also - has SCons installed; following the instructions below will install Cython for - the version of Python installed in the system directories. The minimum - compatible Cython version is 0.29.31. If your distribution does not contain a - suitable version, you may be able to install a more recent version using - Pip. - -* Users of other distributions should install the equivalent packages, which - may have slightly different names. - -* In addition to the operating systems below, Cantera should work on any - Unix-like system where the necessary prerequisites are available, but some - additional configuration may be required. - -.. _sec-ubuntu-debian-reqs: - -Ubuntu & Debian -^^^^^^^^^^^^^^^ - -* Ubuntu 20.04 LTS (Focal Fossa) or newer - -* Debian 11.0 (Bullseye) or newer - -* The following packages must be installed to build any of the Cantera modules using - your choice of package manager:: - - g++ python3 scons libboost-dev libhdf5-dev - - * The HDF5 headers and libraries are not installed to directories on the compiler's - default search path. When building Cantera, these paths need to be specified as - options to ``scons``, for example ``extra_inc_dirs=/usr/include/hdf5/serial`` and - ``extra_lib_dirs=/usr/lib/x86_64-linux-gnu/hdf5/serial``. - -* If you want to use system system packages to provide the following dependencies, - instead of the versions bundled with Cantera, you should also install:: - - libsundials-dev libeigen3-dev libyaml-cpp-dev libfmt-dev - -* In addition to the general packages, building the Python 3 module also requires:: - - cython3 python3-setuptools python3-wheel python3-numpy python3-ruamel.yaml python3-pytest - - * Debian 12.0 (Bookworm) and Ubuntu 23.04 (Lunar Lobster) provide compatible Cython - versions. For older releases, install Cython using Pip. - -* In addition to the general packages, building the Fortran module also requires:: - - gfortran - -* In addition to the general packages, building the MATLAB toolbox also requires: - - * MATLAB version later than 2009a - - * Typically installed to:: - - /opt/MATLAB/R20YYn - - where ``YY`` is a two digit year and ``n`` is either ``a`` or ``b`` - -.. container:: container - - .. container:: row - - .. container:: col-12 text-right - - .. container:: btn btn-primary - :tagname: a - :attributes: href=source-code.html - - Next: Download the Source Code - -.. _sec-fedora-reqs: - -Fedora & RHEL -^^^^^^^^^^^^^ - -* The following packages must be installed to build any of the Cantera modules using - your choice of package manager:: - - gcc-c++ python3 scons boost-devel hdf5-devel - -* If you want to use system system packages to provide the following dependencies, - instead of the versions bundled with Cantera, you should also install: - - sundials-devel eigen3-devel yaml-cpp-devel fmt-devel highfive-devel - -* In addition to the general packages, building the Python 3 module also requires:: - - python3-devel Cython python3-numpy python3-ruamel-yaml python3-pytest - -* In addition to the general packages, building the Fortran module also requires:: - - gcc-gfortran - -* In addition to the general packages, building the MATLAB toolbox also requires: - - * MATLAB version later than 2009a - - * Typically installed to:: - - /opt/MATLAB/R20YYn - - where ``YY`` is a two digit year and ``n`` is either ``a`` or ``b`` - -.. container:: container - - .. container:: row - - .. container:: col-12 text-right - - .. container:: btn btn-primary - :tagname: a - :attributes: href=source-code.html - - Next: Download the Source Code - -.. _sec-opensuse-reqs: - -OpenSUSE & SUSE Linux Enterprise -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -* OpenSUSE Leap 15.5 or newer recommended - -* The following packages must be installed to build any of the Cantera modules using - your choice of package manager:: - - gcc11-c++ python311 libboost_headers1_75_0-devel hdf5-devel python311-pip - - You can specify other version numbers for GCC, Python, and Boost, as long as they meet - Cantera's minimum requirements. - -* You will also need to install ``scons`` using the Pip version installed above. - -* In addition to the general packages, building the Python module also requires:: - - python3-devel - - as well as the following packages installed using Pip: - - numpy wheel cython ruamel.yaml pytest - -* In addition to the general packages, building the Fortran module also requires:: - - gcc11-fortran - -* In addition to the general packages, building the MATLAB toolbox also requires: - - * MATLAB version later than 2009a - - * Typically installed to:: - - /opt/MATLAB/R20YYn - - where ``YY`` is a two digit year and ``n`` is either ``a`` or ``b`` - -.. container:: container - - .. container:: row - - .. container:: col-12 text-right - - .. container:: btn btn-primary - :tagname: a - :attributes: href=source-code.html - - Next: Download the Source Code - -.. _sec-windows: - -Windows -------- - -General Notes -^^^^^^^^^^^^^ - -* The build process will produce a Python module compatible with the version of - Python used for the compilation. To generate different modules for other - versions of Python, you will need to install those versions of Python and - recompile. - -* The following instructions use the versions of Python downloaded from - https://www.python.org/downloads/, but alternate installations such as the - Anaconda distribution of Python can be used as well. - -* If you want to build the Matlab toolbox and you have a 64-bit copy of Windows, - by default you will be using a 64-bit copy of Matlab, and therefore you need - to compile Cantera in 64-bit mode. For simplicity, it is highly recommended - that you use a 64-bit version of Python to handle this automatically. - -* It is generally helpful to have SCons and Python in your ``PATH`` environment - variable. This can be done by checking the appropriate box during the - installation of Python or can be accomplished by adding the top-level Python - directory and the ``Scripts`` subdirectory (for example, - ``C:\Python36;C:\Python36\Scripts``) to your ``PATH``. The dialog to change - the ``PATH`` is accessible from:: - - Control Panel > System and Security > System > Advanced System Settings > Environment Variables - - Make sure that the installation of Python that has SCons comes first on your - ``PATH``. - -* In order to use SCons to install Cantera to a system folder (for example, - ``C:\Program Files\Cantera``) you must run the ``scons install`` command in a - command prompt that has been launched by selecting the *Run as Administrator* - option. - -.. _sec-windows-reqs: - -Windows Requirements -^^^^^^^^^^^^^^^^^^^^^^^ - -* Windows 7 or later; either 32-bit or 64-bit - -* To build any of the Cantera modules, you will need to install - - * Python - - * https://www.python.org/downloads/ - - * Cantera supports Python 3.8 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`` - - * SCons - - * https://pypi.org/project/SCons/ - - * Be sure to choose the appropriate architecture for your system - either - 32-bit or 64-bit - - * One of the following supported compilers - - * Microsoft compilers - - * https://visualstudio.microsoft.com/downloads/ - - * Known to work with Visual Studio 2017 (MSVC 14.1), Visual Studio 2019 - (MSVC 14.2), and Visual Studio 2022 (MSVC 14.3). - - * MinGW compilers - - * http://mingw-w64.org/ - - * http://tdm-gcc.tdragon.net/ - - * Known to work with Mingw-w64 12.2. - - * The Boost headers - - * https://www.boost.org/doc/libs/1_82_0/more/getting_started/windows.html#get-boost - - * It is not necessary to compile the Boost libraries since Cantera only uses - the headers from Boost - -* In addition to the general software, building the Python module also requires - several Python packages: Cython, NumPy, setuptools, wheel, ruamel.yaml, and pytest. - All of these can be installed using `pip`: - - .. code:: bash - - py -m pip install setuptools wheel cython numpy ruamel.yaml pytest - -* In addition to the general software, building the MATLAB toolbox also requires: - - * MATLAB version later than 2009a - - * Typically installed to:: - - C:\Program Files\MATLAB\R20YYn - - where ``YY`` is a two digit year and ``n`` is either ``a`` or ``b`` - -.. container:: container - - .. container:: row - - .. container:: col-12 text-right - - .. container:: btn btn-primary - :tagname: a - :attributes: href=source-code.html - - Next: Download the Source Code - -.. _sec-macos: - -macOS ------ - -General Notes -^^^^^^^^^^^^^ - -* Cantera 2.5.0 and higher do not support Python 2, which may be installed by default - on your computer. You must install Python 3 from another source to be able to build - Cantera. The instructions below use Homebrew. - -.. _sec-mac-os-reqs: - -macOS Requirements -^^^^^^^^^^^^^^^^^^ - -* macOS 10.15 (Catalina) is required; Homebrew requires 11.0 or newer. - -* To build any of the Cantera interfaces, you will need to install - - * Xcode - - * Download and install from the App Store - - * From a Terminal, run: - - .. code:: bash - - sudo xcode-select --install - - and agree to the Xcode license agreement - - * Homebrew - - * https://brew.sh - - * From a Terminal, run: - - .. code:: bash - - /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" - - * Once Homebrew is installed, the rest of the dependencies can be installed with: - - .. code:: bash - - brew install python scons boost git hdf5 libomp - - Note that brew installs Python 3 by default, but does not over-write the existing - system Python. When you want to use the brew-installed Python, check to make sure - that ``python3`` and ``pip3`` refer to the Homebrew installation by running: - - .. code:: bash - - which python3 - which pip3 - - If these commands do not include the Homebrew path, you can run the correct ones as - ``$(brew --prefix)/bin/python3`` and ``$(brew --prefix)/bin/pip3``. - -* In addition to the general software, building the Python module also requires: - - .. code:: bash - - $(brew --prefix)/bin/pip3 install cython numpy wheel setuptools ruamel.yaml pytest - -* In addition to the general software, building the Fortran module also requires: - - .. code:: bash - - brew install gcc - -* In addition to the general software, building the MATLAB toolbox also requires: - - * MATLAB version later than 2009a - - * Typically installed to:: - - /Applications/MATLAB_R20YYn.app - - where ``YY`` is a two digit year and ``n`` is either ``a`` or ``b`` - -* The Homebrew header and library directories will not be on the path for the system - compiler (Xcode), so when compiling Cantera, you will need to provide the command line - options ``extra_inc_dirs=$(brew --prefix)/include`` and - ``extra_lib_dirs=$(brew --prefix)/lib``. - -.. container:: container - - .. container:: row - - .. container:: col-12 text-right - - .. container:: btn btn-primary - :tagname: a - :attributes: href=source-code.html - - Next: Download the Source Code diff --git a/pages/compiling/config-options-dev.rst b/pages/compiling/config-options-dev.rst deleted file mode 100644 index 72d8e541a..000000000 --- a/pages/compiling/config-options-dev.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. title: Configuration Options (development version) - -.. _scons-config-dev: - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Configuration Options</h1> - - .. class:: lead - - This document lists the options available for compiling Cantera with - SCons. This list is for the development version of Cantera. For - the current release, see `this list <config-options.html>`_. - - The default values are operating-system dependent. To see the defaults for - your current operating system, run the command: - - .. code:: bash - - scons help - - from the command prompt. - - The following options can be passed to SCons to customize the Cantera - build process. They should be given in the form: - - .. code:: bash - - scons build option1=value1 option2=value2 - - Variables set in this way will be stored in the ``cantera.conf`` file and reused - automatically on subsequent invocations of SCons. Alternatively, the - configuration options can be entered directly into ``cantera.conf`` before - running ``scons build``. The format of this file is: - - .. code:: python - - option1 = 'value1' - option2 = 'value2' - -.. - The options list is generated using 'scons help --restructured-text --dev' - and is copied manually into the folder during the GH actions - -.. include:: pages/compiling/scons-config-options-dev.rst diff --git a/pages/compiling/config-options.rst b/pages/compiling/config-options.rst deleted file mode 100644 index a02205864..000000000 --- a/pages/compiling/config-options.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. title: Configuration Options - -.. _scons-config: - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Configuration Options</h1> - - .. class:: lead - - This document lists the options available for compiling Cantera with - SCons. This list is for the current release of Cantera, version 3.0.0. For - the development version, see `this list <config-options-dev.html>`_. - - The default values are operating-system dependent. To see the defaults for your current operating - system, run the command: - - .. code:: bash - - scons help - - from the command prompt. - - The following options can be passed to SCons to customize the Cantera - build process. They should be given in the form: - - .. code:: bash - - scons build option1=value1 option2=value2 - - Variables set in this way will be stored in the ``cantera.conf`` file and reused - automatically on subsequent invocations of SCons. Alternatively, the - configuration options can be entered directly into ``cantera.conf`` before - running ``scons build``. The format of this file is: - - .. code:: python - - option1 = 'value1' - option2 = 'value2' - -.. - Generate the options list with 'scons help --restructured-text --output=scons-config-options.rst' - -.. include:: pages/compiling/scons-config-options.rst diff --git a/pages/compiling/configure-build-dev.rst b/pages/compiling/configure-build-dev.rst deleted file mode 100644 index f6c53319c..000000000 --- a/pages/compiling/configure-build-dev.rst +++ /dev/null @@ -1,306 +0,0 @@ -.. title: Configure and Build (development version) -.. description: Configure and Build Cantera - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Configure & Build Cantera</h1> - - .. class:: lead - - These directions are for the development version of Cantera. For - the current release, see `these instructions <configure-build.html>`_. - -.. _sec-determine-config-dev: - -Determine configuration options -=============================== - -* Run ``scons help --options`` to see a list of all of the configuration options for - Cantera, or see all of the options on the :ref:`Configuration Options <scons-config-dev>` - page. - -* Configuration options are specified as additional arguments to the ``scons`` - command. For example: - - .. code:: bash - - scons command option_name=value - - where ``scons`` is the program that manages the build steps, and ``command`` - is most commonly one of - - * ``build`` - * ``test`` - * ``clean`` - - Other commands are explained in the :ref:`Build Commands <sec-build-commands-dev>` - section. - -* SCons saves configuration options specified on the command line in the file - ``cantera.conf`` in the root directory of the source tree, so generally it is - not necessary to respecify configuration options when rebuilding Cantera. To - unset a previously set configuration option, either remove the corresponding - line from ``cantera.conf`` or use the syntax: - - .. code:: bash - - scons command option_name= - -* Sometimes, changes in your environment can cause SCons's configuration tests - (for example, checking for libraries or compiler capabilities) to unexpectedly fail. - To force SCons to re-run these tests rather than trusting the cached results, - run scons with the option ``--config=force``. - -* The following lists of options are not complete, they show only some commonly - used options. The entire list of options can be found on the - :ref:`Configuration options <scons-config-dev>` page. - -Common Options -^^^^^^^^^^^^^^ - -* :ref:`debug <debug-dev>` -* :ref:`optimize <optimize-dev>` -* :ref:`prefix <prefix-dev>` - -Specifying Paths for Cantera's Dependencies -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -* :ref:`blas_lapack_libs <blas-lapack-libs-dev>` - - * On OS X, the Accelerate framework is automatically used to provide - optimized versions of BLAS and LAPACK, so the ``blas_lapack_libs`` - option should generally be left unspecified. - -* :ref:`blas_lapack_dir <blas-lapack-dir-dev>` -* :ref:`boost_inc_dir <boost-inc-dir-dev>` -* :ref:`sundials_include <sundials-include-dev>` -* :ref:`sundials_libdir <sundials-libdir-dev>` -* :ref:`hdf_include <hdf-include-dev>` -* :ref:`hdf_libdir <hdf-libdir-dev>` -* :ref:`extra_inc_dirs <extra-inc-dirs-dev>` -* :ref:`extra_lib_dirs <extra-lib-dirs-dev>` - -Python Module Options -^^^^^^^^^^^^^^^^^^^^^ - -Compiling the Cantera Python module requires that NumPy and Cython are installed -for the target installation of Python. The following SCons options control how -the Python module is built: - -* :ref:`python_package <python-package-dev>` -* :ref:`python_cmd <python-cmd-dev>` - - * By default, SCons will try to build the full Python interface for copy of - Python that is running SCons. Use this option if you wish to build Cantera - for a different Python installation. - -* :ref:`python_prefix <python-prefix-dev>` - -Windows Only Options -^^^^^^^^^^^^^^^^^^^^ - -.. note:: - - The ``cantera.conf`` file uses the backslash character ``\`` as an escape - character. When modifying this file, backslashes in paths need to be escaped - like this: ``boost_inc_dir = 'C:\\Program Files (x86)\\boost\\include'`` - This does not apply to paths specified on the command line. Alternatively, - you can use forward slashes (``/``) in paths. - -* In Windows there aren't any proper default locations for many of the packages - that Cantera depends on, so you will need to specify these paths explicitly. - -* Remember to put double quotes around any paths with spaces in them, such as - ``"C:\Program Files"``. - -* By default, SCons attempts to use the same architecture as the copy of Python - that is running SCons, and the most recent installed version of the Visual - Studio compiler. If you aren't building the Python module, you can override - this with the configuration options ``target_arch`` and ``msvc_toolset_version``. - -* To compile with MinGW, specify the :ref:`toolchain <toolchain-dev>` option:: - - toolchain=mingw - -* :ref:`msvc_toolset_version <_msvc-toolset-version-dev>` -* :ref:`msvc_version <msvc-version-dev>` -* :ref:`target_arch <target-arch-dev>` -* :ref:`toolchain <toolchain-dev>` - -MATLAB Toolbox Options -^^^^^^^^^^^^^^^^^^^^^^ - -Building the MATLAB toolbox requires an installed copy of MATLAB, and the path -to the directory where MATLAB is installed must be specified using the following -option: - -* :ref:`matlab_toolbox <matlab-toolbox-dev>` -* :ref:`matlab_path <matlab-path-dev>` - -Fortran Module Options -^^^^^^^^^^^^^^^^^^^^^^ - -Building the Fortran module requires a compatible Fortran compiler. SCons will -attempt to find a compatible compiler by default in the ``PATH`` environment -variable. The following options control how the Fortran module is built: - -* :ref:`f90_interface <f90-interface-dev>` -* :ref:`FORTRAN <fortran-dev>` - -Documentation Options -^^^^^^^^^^^^^^^^^^^^^ - -The following options control if the documentation is built: - -* :ref:`doxygen_docs <doxygen-docs-dev>` -* :ref:`sphinx_docs <sphinx-docs-dev>` - -Less Common Options -^^^^^^^^^^^^^^^^^^^ - -* :ref:`CC <cc-dev>` -* :ref:`CXX <cxx-dev>` -* :ref:`env_vars <env-vars-dev>` -* :ref:`layout <layout-dev>` -* :ref:`VERBOSE <verbose-dev>` -* :ref:`gtest_flags <gtest-flags-dev>` - -.. _sec-build-commands-dev: - -Build Commands -============== - -The following *commands* are possible as arguments to SCons: - -.. code:: bash - - scons command - -* ``scons help`` - Print a list of available SCons commands. - -* ``scons help --options`` - Print a description of user-specifiable options. - -* ``scons build`` - Compile Cantera and the language interfaces using - default options. - -* ``scons clean`` - Delete files created while building Cantera. - -* ``scons install`` - Install Cantera. - -* ``scons uninstall`` - Uninstall Cantera. - -* ``scons test`` - Run all tests which did not previously pass or for which the - results may have changed. - -* ``scons test-reset`` - Reset the passing status of all tests. - -* ``scons test-clean`` - Delete files created while running the tests. - -* ``scons test-help`` - List available tests. - -* ``scons test-NAME`` - Run the test named ``NAME``. - -* ``scons <command> dump`` - Dump the state of the SCons environment to the - screen instead of doing ``<command>``, for example, - ``scons build dump``. For debugging purposes. - -* ``scons samples`` - Compile the C++ and Fortran samples. - -* ``scons msi`` - Build a Windows installer (.msi) for Cantera. - -* ``scons sphinx`` - Build the Sphinx documentation - -* ``scons doxygen`` - Build the Doxygen documentation - -Compile Cantera & Test -====================== - -* Run SCons with the list of desired configuration options: - - .. code:: bash - - scons build ... - -* If Cantera compiles successfully, you should see a message that looks like:: - - ******************************************************* - Compilation completed successfully. - - - To run the test suite, type 'scons test'. - - To list available tests, type 'scons test-help'. - - To install, type 'scons install'. - ******************************************************* - -* If you do not see this message, check the output for errors to see what went - wrong. You may also need to examine the contents of ``config.log``. - -* Cantera has a series of tests that can be run with the command: - -.. code:: bash - - scons test - -* When the tests finish, you should see a summary indicating the number of - tests that passed and failed. - -* If you have tests that fail, try looking at the following to determine the - source of the error: - - * Messages printed to the console while running ``scons test`` - * Output files generated by the tests - -Building Documentation -^^^^^^^^^^^^^^^^^^^^^^ - -To build the Cantera HTML documentation, run the commands: - -.. code:: bash - - scons doxygen - scons sphinx - -or append the options ``sphinx_docs=y`` and ``doxygen_docs=y`` to the build -command: - -.. code:: bash - - scons build doxygen_docs=y sphinx_docs=y - -.. container:: container - - .. container:: row - - .. container:: col-6 text-left - - .. container:: btn btn-primary - :tagname: a - :attributes: href=source-code.html - - Previous: Download the Source Code - - - .. container:: col-6 text-right - - .. container:: btn btn-primary - :tagname: a - :attributes: href=dependencies.html - - Next: Dependencies diff --git a/pages/compiling/configure-build.rst b/pages/compiling/configure-build.rst deleted file mode 100644 index 2b6a24610..000000000 --- a/pages/compiling/configure-build.rst +++ /dev/null @@ -1,314 +0,0 @@ -.. title: Configure and Build -.. description: Configure and Build Cantera - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Configure & Build Cantera</h1> - - .. class:: lead - - These directions are for the current release of Cantera, version 3.0. For - the development version, see `these instructions <configure-build-dev.html>`_. - -.. _sec-determine-config: - -Determine configuration options -=============================== - -* Run ``scons help --options`` to see a list of all of the configuration options for - Cantera, or see all of the options on the :ref:`Configuration Options <scons-config>` - page. - -* Configuration options are specified as additional arguments to the ``scons`` - command. For example: - - .. code:: bash - - scons command option_name=value - - where ``scons`` is the program that manages the build steps, and ``command`` - is most commonly one of - - * ``build`` - * ``test`` - * ``clean`` - - Other commands are explained in the :ref:`Build Commands <sec-build-commands>` - section. - -* SCons saves configuration options specified on the command line in the file - ``cantera.conf`` in the root directory of the source tree, so generally it is - not necessary to respecify configuration options when rebuilding Cantera. To - unset a previously set configuration option, either remove the corresponding - line from ``cantera.conf`` or use the syntax: - - .. code:: bash - - scons command option_name= - -* Sometimes, changes in your environment can cause SCons's configuration tests - (for example, checking for libraries or compiler capabilities) to unexpectedly fail. - To force SCons to re-run these tests rather than trusting the cached results, - run scons with the option ``--config=force``. - -* The following lists of options are not complete, they show only some commonly - used options. The entire list of options can be found on the - :ref:`Configuration options <scons-config>` page. - -Common Options -^^^^^^^^^^^^^^ - -* :ref:`debug <debug>` -* :ref:`optimize <optimize>` -* :ref:`prefix <prefix>` - -Specifying Paths for Cantera's Dependencies -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -* :ref:`blas_lapack_libs <blas-lapack-libs>` - - * On OS X, the Accelerate framework is automatically used to provide - optimized versions of BLAS and LAPACK, so the ``blas_lapack_libs`` - option should generally be left unspecified. - -* :ref:`blas_lapack_dir <blas-lapack-dir>` -* :ref:`boost_inc_dir <boost-inc-dir>` -* :ref:`sundials_include <sundials-include>` -* :ref:`sundials_libdir <sundials-libdir>` -* :ref:`hdf_include <hdf-include>` -* :ref:`hdf_libdir <hdf-libdir>` -* :ref:`extra_inc_dirs <extra-inc-dirs>` -* :ref:`extra_lib_dirs <extra-lib-dirs>` - -General Python Module Options -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -By default, SCons will try to build the full Python interface for -whichever version of Python is running SCons. This requires that -NumPy is installed for that version of Python, and that Cython is -installed for whichever Python is running SCons. The following SCons -options control how the Python module is built: - -* :ref:`python_cmd <python-cmd>` -* :ref:`python_package <python-package>` -* :ref:`python_prefix <python-prefix>` - -Windows Only Options -^^^^^^^^^^^^^^^^^^^^ - -.. note:: - - The ``cantera.conf`` file uses the backslash character ``\`` as an escape - character. When modifying this file, backslashes in paths need to be escaped - like this: ``boost_inc_dir = 'C:\\Program Files (x86)\\boost\\include'`` - This does not apply to paths specified on the command line. Alternatively, - you can use forward slashes (``/``) in paths. - -* In Windows there aren't any proper default locations for many of the packages - that Cantera depends on, so you will need to specify these paths explicitly. - -* Remember to put double quotes around any paths with spaces in them, such as - ``"C:\Program Files"``. - -* By default, SCons attempts to use the same architecture as the copy of Python - that is running SCons, and the most recent installed version of the Visual - Studio compiler. If you aren't building the Python module, you can override - this with the configuration options ``target_arch`` and ``msvc_toolset_version``. - -* To compile with MinGW, specify the :ref:`toolchain <toolchain>` option:: - - toolchain=mingw - -* :ref:`msvc_toolset_version <msvc-toolset-version>` -* :ref:`msvc_version <msvc-version>` -* :ref:`target_arch <target-arch>` -* :ref:`toolchain <toolchain>` - -MATLAB Toolbox Options -^^^^^^^^^^^^^^^^^^^^^^ - -Building the MATLAB toolbox requires an installed copy of MATLAB, and the path -to the directory where MATLAB is installed must be specified using the following -option: - -* :ref:`matlab_toolbox <matlab-toolbox>` -* :ref:`matlab_path <matlab-path>` - -Fortran Module Options -^^^^^^^^^^^^^^^^^^^^^^ - -Building the Fortran module requires a compatible Fortran compiler. SCons will -attempt to find a compatible compiler by default in the ``PATH`` environment -variable. The following options control how the Fortran module is built: - -* :ref:`f90_interface <f90-interface>` -* :ref:`FORTRAN <fortran>` - -Documentation Options -^^^^^^^^^^^^^^^^^^^^^ - -The following options control if the documentation is built: - -* :ref:`doxygen_docs <doxygen-docs>` -* :ref:`sphinx_docs <sphinx-docs>` - -Less Common Options -^^^^^^^^^^^^^^^^^^^ - -* :ref:`CC <cc>` -* :ref:`CXX <cxx>` -* :ref:`env_vars <env-vars>` -* :ref:`layout <layout>` -* :ref:`VERBOSE <verbose>` -* :ref:`gtest_flags <gtest-flags>` - -.. _sec-build-commands: - -Build Commands -============== - -The following *commands* are possible as arguments to SCons: - -.. code:: bash - - scons command - -* ``scons help`` - Print a list of available SCons commands. - -* ``scons help --options`` - Print a description of user-specifiable options. - -* ``scons build`` - Compile Cantera and the language interfaces using - default options. - -* ``scons clean`` - Delete files created while building Cantera. - -* ``scons install`` - Install Cantera. - -* ``scons uninstall`` - Uninstall Cantera. - -* ``scons test`` - Run all tests which did not previously pass or for which the - results may have changed. - -* ``scons test-reset`` - Reset the passing status of all tests. - -* ``scons test-clean`` - Delete files created while running the tests. - -* ``scons test-help`` - List available tests. - -* ``scons test-NAME`` - Run the test named ``NAME``. - -* ``scons <command> dump`` - Dump the state of the SCons environment to the - screen instead of doing ``<command>``, for example, - ``scons build dump``. For debugging purposes. - -* ``scons samples`` - Compile the C++ and Fortran samples. - -* ``scons msi`` - Build a Windows installer (.msi) for Cantera. - -* ``scons sphinx`` - Build the Sphinx documentation - -* ``scons doxygen`` - Build the Doxygen documentation - -Compile Cantera & Test -====================== - -* Run SCons with the list of desired configuration options: - - .. code:: bash - - scons build ... - -.. caution:: - - If you are compiling with a version of SCons installed by Homebrew on macOS, the appropriate - way to perform any commands with SCons is - - .. code:: bash - - python3 /usr/local/bin/scons command ... - - This ensures that the dependencies are chosen from the correct version of Python. - -* If Cantera compiles successfully, you should see a message that looks like:: - - ******************************************************* - Compilation completed successfully. - - - To run the test suite, type 'scons test'. - - To list available tests, type 'scons test-help'. - - To install, type 'scons install'. - ******************************************************* - -* If you do not see this message, check the output for errors to see what went - wrong. You may also need to examine the contents of ``config.log``. - -* Cantera has a series of tests that can be run with the command: - -.. code:: bash - - scons test - -* When the tests finish, you should see a summary indicating the number of - tests that passed and failed. - -* If you have tests that fail, try looking at the following to determine the - source of the error: - - * Messages printed to the console while running ``scons test`` - * Output files generated by the tests - -Building Documentation -^^^^^^^^^^^^^^^^^^^^^^ - -To build the Cantera HTML documentation, run the commands: - -.. code:: bash - - scons doxygen - scons sphinx - -or append the options ``sphinx_docs=y`` and ``doxygen_docs=y`` to the build -command: - -.. code:: bash - - scons build doxygen_docs=y sphinx_docs=y - -.. container:: container - - .. container:: row - - .. container:: col-6 text-left - - .. container:: btn btn-primary - :tagname: a - :attributes: href=source-code.html - - Previous: Download the Source Code - - - .. container:: col-6 text-right - - .. container:: btn btn-primary - :tagname: a - :attributes: href=dependencies.html - - Next: Dependencies diff --git a/pages/compiling/dependencies.rst b/pages/compiling/dependencies.rst deleted file mode 100644 index f81ddd92a..000000000 --- a/pages/compiling/dependencies.rst +++ /dev/null @@ -1,214 +0,0 @@ -.. title: Software used by Cantera - -.. _sec-dependencies: - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Software used by Cantera</h1> - - .. class:: lead - - This section lists the versions of third-party software that are required to - build and use Cantera. - -Compilers ---------- - -You must have one of the following C++ compilers installed on your system. A -Fortran compiler is required only if you plan to build the Fortran module. - -* GNU compilers (C/C++/Fortran) - - * Known to work with versions 9.4 and 11.4. Expected to work with version >= 9.0. - -* Clang/LLVM (C/C++) - - * Known to work with versions 10 and 12. Expected to work with version - >= 5.0 - * Works with the versions included in Xcode 13.0 and 14.3.1. - -* Intel compilers (C/C++/Fortran) - - * Known to work with the Intel OneAPI Compilers (version 2022.0.2). - * Some earlier versions of the Intel compiler (including the 2017 version) are - **NOT RECOMMENDED** because of a bug in the C compiler. - -* 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). - -* MinGW (C/C++/Fortran) - - * http://mingw-w64.org/doku.php (64-bit) - * http://tdm-gcc.tdragon.net/ (64-bit) - * Known to work with Mingw-w64 12.2. - -Other Required Software ------------------------ - -* SCons: - - * http://scons.org/tag/releases.html - * Works with versions >= 3.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. - -* Boost - - * https://www.boost.org/users/download/ - * Known to work with versions 1.71, 1.74, and 1.82; Expected to work with versions >= 1.70 - * Only the "header-only" portions of Boost are required. Cantera does not - currently depend on any of the compiled Boost libraries. - -* SUNDIALS - - * If SUNDIALS is not installed and you have checked out the Cantera source code using - 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. Expected to work with versions <= 7.0. - * 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>`` - -* Eigen - - * If Eigen is not installed and you have checked out the Cantera source code using - Git, Eigen will be automatically downloaded and installed with Cantera. - * https://eigen.tuxfamily.org/index.php?title=Main_Page - * Known to work with version 3.4.0. - -* fmt - - * If fmt (previously known as cppformat) is not installed and you have checked out - the 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 version 9.1.0. - -* yaml-cpp - - * If yaml-cpp is not installed and you have checked out the Cantera source code using - Git, it will be automatically downloaded and the necessary portions will be compiled - and installed with Cantera. - * https://github.com/jbeder/yaml-cpp - * Known to work with version 0.7.0. Version 0.6.0 or newer is required. - -Optional Dependencies ---------------------- - -* `Numpy <https://www.numpy.org/>`__ - - * 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. - -* `Cython <https://cython.org/>`__ - - * Required version >=0.29.31 to build the Python module. - -* `Pip <https://pip.pypa.io/en/stable/installing/>`__ (Python) - - * Required to build the Cantera Python module. - * Provides the ``pip`` command which can be used to install most of - the other Python dependencies. - -* `wheel <https://pypi.org/project/wheel/>`__ (Python) - - * Required to build the Cantera Python module. - -* `setuptools <https://pypi.org/project/setuptools/>`__ (Python) - - * Required to build the Cantera Python module. - -* `Ruamel.yaml <https://pypi.org/project/ruamel.yaml/>`__ (Python) - - * Required to convert input files from Chemkin, 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 - -* `libhdf5 <https://www.hdfgroup.org/solutions/hdf5/>`__ - - * Required to read and write data files in the HDF5 format - * Known to work with versions 1.12 and 1.14. - -* `HighFive <https://github.com/BlueBrain/HighFive>`__ - - * Required to read and write data files in the HDF5 format - * If HighFive is not installed and you have checked out the Cantera source code - using Git, HighFive will be automatically downloaded and the necessary portions will - be compiled as part of the Cantera build process. - * Version 2.5.0 or newer is required. - -* `Google Test <https://github.com/google/googletest>`__ - - * If Google Test is not installed and you have checked out the Cantera source code - using Git, Google Test will be automatically downloaded and the necessary portions - will be compiled as part of the Cantera build process. - * Required to run significant portions of the test suite. - * Known to work with version 1.11.0. - -* `pytest <https://pytest.org>`__ - - * Required to run the Python test suite. - * Known to work with version 7.2.0 - -* Matlab - - * Required to build the Cantera Matlab toolbox. - * Known to work with 2022a. Expected to work with versions >= 2009a. - -* `Windows Installer XML (WiX) toolset <http://wixtoolset.org/>`__ - - * Required to build MSI installers on Windows. - * Known to work with versions 3.5 and 3.8. - -* Packages required for building Sphinx documentation - - * `Sphinx <http://www.sphinx-doc.org/en/stable/>`__ - * `PyData Sphinx theme <https://pydata-sphinx-theme.readthedocs.io/en/stable/>`__ - * `Pygments <http://pygments.org/>`__ - * `pyparsing <https://sourceforge.net/projects/pyparsing/>`__ - * `sphinx-argparse <https://sphinx-argparse.readthedocs.io/en/latest/>`__ - * `doxylink <https://pythonhosted.org/sphinxcontrib-doxylink/>`__ - * `matlabdomain <https://pypi.org/project/sphinxcontrib-matlabdomain>`__ - -* `Doxygen <http://doxygen.nl/>`__ - - * Required for building the C++ API Documentation - * Version 1.8 or newer is recommended. - -* `Graphviz <https://www.graphviz.org/>`__ - - * Required to build the dependency graph images in the C++ API Documentation - * Known to work with version 2.40.1, expected to work with versions >=2.40.1 - -.. container:: container - - .. container:: row - - .. container:: col-6 text-left - - .. container:: btn btn-primary - :tagname: a - :attributes: href=configure-build.html - - Previous: Configure & Build - - - .. container:: col-6 text-right - - .. container:: btn btn-primary - :tagname: a - :attributes: href=special-cases.html - - Next: Special Cases diff --git a/pages/compiling/scons-config-options-dev.rst b/pages/compiling/scons-config-options-dev.rst deleted file mode 100644 index 4f5d6daa0..000000000 --- a/pages/compiling/scons-config-options-dev.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. - This file is a place-holder - -Options List -^^^^^^^^^^^^ - -This file is a placeholder for a generated reST file containing a list of options. -The content replacing this file is generated from within Cantera's main folder as:: - - $ scons help --restructured-text --dev --output=scons-config-options-dev.rst diff --git a/pages/compiling/scons-config-options.rst b/pages/compiling/scons-config-options.rst deleted file mode 100644 index f7df9a0f0..000000000 --- a/pages/compiling/scons-config-options.rst +++ /dev/null @@ -1,722 +0,0 @@ -Options List -^^^^^^^^^^^^ - -.. _msvc-version: - -* ``msvc_version``: [ ``string`` ] - Version of Visual Studio to use. The default is the newest installed version. - Note that since multiple MSVC toolsets can be installed for a single version of - Visual Studio, you probably want to use ``msvc_toolset_version`` unless you - specifically installed multiple versions of Visual Studio. Windows MSVC only. - - - default: ``''`` - -.. _msvc-toolset-version: - -* ``msvc_toolset_version``: [ ``string`` ] - Version of the MSVC toolset to use. The default is the default version for - the given ``msvc_version``. Note that the toolset selected here must be - installed in the MSVC version selected by ``msvc_version``. The default - toolsets associated with various Visual Studio versions are: - - * ``14.1`` (``14.1x``): Visual Studio 2017 - * ``14.2`` (``14.2x``): Visual Studio 2019 - * ``14.3`` (``14.3x``): Visual Studio 2022. - - For version numbers in parentheses, ``x`` is a placeholder for a minor version - number. Windows MSVC only. - - - default: ``''`` - -.. _target-arch: - -* ``target_arch``: [ ``'amd64'`` | ``'x86'`` ] - Target architecture. The default is the same architecture as the - installed version of Python. Windows only. - - - default: platform dependent - - - Windows: ``'amd64'`` - -.. _toolchain: - -* ``toolchain``: [ ``'msvc'`` | ``'mingw'`` | ``'intel'`` ] - The preferred compiler toolchain. If MSVC is not on the path but - ``g++`` is on the path, ``mingw`` is used as a backup. Windows only. - - - default: platform dependent - - - Windows: ``'msvc'`` - -.. _ar: - -* ``AR``: [ ``string`` ] - The archiver to use. - - - default: ``'${AR}'`` - -.. _cxx: - -* ``CXX``: [ ``string`` ] - The C++ compiler to use. - - - default: ``'${CXX}'`` - -.. _cxx-flags: - -* ``cxx_flags``: [ ``string`` ] - Compiler flags passed to the C++ compiler only. Separate multiple - options with spaces, for example, ``"cxx_flags='-g -Wextra -O3 --std=c++14'"`` - - - default: compiler dependent - - - If using ``MSVC``: ``'/EHsc /std:c++17'`` - - Otherwise: ``'-std=c++17'`` - -.. _cc: - -* ``CC``: [ ``string`` ] - The C compiler to use. This is only used to compile CVODE. - - - default: ``'${CC}'`` - -.. _cc-flags: - -* ``cc_flags``: [ ``string`` ] - Compiler flags passed to both the C and C++ compilers, regardless of - optimization level. - - - default: compiler dependent - - - If using ``MSVC``: ``'/MD /nologo /D_SCL_SECURE_NO_WARNINGS /D_CRT_SECURE_NO_WARNINGS'`` - - If using ``Clang``: ``'-fcolor-diagnostics'`` - - Otherwise: ``''`` - -.. _prefix: - -* ``prefix``: [ ``path/to/prefix`` ] - Set this to the directory where Cantera should be installed. If the Python - executable found during compilation is managed by ``conda``, the installation - ``prefix`` defaults to the corresponding environment and the ``conda`` layout - will be used for installation (specifying any of the options ``prefix``, - ``python_prefix``, ``python_cmd``, or ``layout`` will override this default). On - Windows systems, ``$ProgramFiles`` typically refers to ``"C:\Program Files"``. - - - default: platform dependent - - - Windows: ``'$ProgramFiles\Cantera'`` - - Otherwise: ``'/usr/local'`` - -.. _libdirname: - -* ``libdirname``: [ ``path/to/libdirname`` ] - Set this to the directory where Cantera libraries should be installed. - Some distributions (for example, Fedora/RHEL) use ``lib64`` instead of ``lib`` - on 64-bit systems or could use some other library directory name instead of - ``lib``, depending on architecture and profile (for example, Gentoo ``libx32`` - on x32 profile). If the user didn't set the ``libdirname`` configuration - variable, set it to the default value ``lib`` - - - default: ``'lib'`` - -.. _python-package: - -* ``python_package``: [ ``'n'`` | ``'y'`` | ``'full'`` | ``'minimal'`` | ``'none'`` | ``'default'`` ] - If you plan to work in Python, then you need the ``full`` Cantera Python - package. If, on the other hand, you will only use Cantera from some - other language (for example, MATLAB or Fortran 90/95) and only need Python - to process YAML files, then you only need a ``minimal`` subset of the - package and Cython and NumPy are not necessary. The ``none`` option - doesn't install any components of the Python interface. 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``. - - - default: ``'default'`` - -.. _python-sdist: - -* ``python_sdist``: [ ``'yes'`` | ``'no'`` ] - Setting this option to True builds the Python sdist. - - - default: ``'no'`` - -.. _python-cmd: - -* ``python_cmd``: [ ``path/to/python_cmd`` ] - Cantera needs to know where to find the Python interpreter. If - ``PYTHON_CMD`` is not set, then the configuration process will use the - same Python interpreter being used by SCons. - - - default: ``'${PYTHON_CMD}'`` - -.. _python-prefix: - -* ``python_prefix``: [ ``path/to/python_prefix`` ] - Use this option if you want to install the Cantera Python package to - an alternate location. On Unix-like systems, the default is the same - as the ``prefix`` option. If the ``python_prefix`` option is set to - the empty string or the ``prefix`` option is not set, then the package - will be installed to the system default ``site-packages`` directory. - To install to the current user's ``site-packages`` directory, use - ``python_prefix=USER``. - - - default: platform dependent - - - Otherwise: ``''`` - -.. _matlab-toolbox: - -* ``matlab_toolbox``: [ ``'n'`` | ``'y'`` | ``'default'`` ] - This variable controls whether the MATLAB toolbox will be built. If - set to ``y``, you will also need to set the value of the ``matlab_path`` - variable. If set to ``default``, the MATLAB toolbox will be built if - ``matlab_path`` is set. - - - default: ``'default'`` - -.. _matlab-path: - -* ``matlab_path``: [ ``path/to/matlab_path`` ] - Path to the MATLAB install directory. This should be the directory - containing the ``extern``, ``bin``, etc. subdirectories. Typical values - are: ``"C:\Program Files\MATLAB\R2021a"`` on Windows, - ``"/Applications/MATLAB_R2021a.app"`` on macOS, or - ``"/opt/MATLAB/R2021a"`` on Linux. - - - default: ``''`` - -.. _f90-interface: - -* ``f90_interface``: [ ``'n'`` | ``'y'`` | ``'default'`` ] - This variable controls whether the Fortran 90/95 interface will be - built. If set to ``default``, the builder will look for a compatible - Fortran compiler in the ``PATH`` environment variable, and compile - the Fortran 90 interface if one is found. - - - default: ``'default'`` - -.. _fortran: - -* ``FORTRAN``: [ ``path/to/FORTRAN`` ] - The Fortran (90) compiler. If unspecified, the builder will look for a - compatible compiler (pgfortran, gfortran, ifort, ifx, g95) in the ``PATH`` - environment variable. Used only for compiling the Fortran 90 interface. - - - default: ``''`` - -.. _fortranflags: - -* ``FORTRANFLAGS``: [ ``string`` ] - Compilation options for the Fortran (90) compiler. - - - default: ``'-O3'`` - -.. _coverage: - -* ``coverage``: [ ``'yes'`` | ``'no'`` ] - Enable collection of code coverage information with gcov. - Available only when compiling with gcc. - - - default: ``'no'`` - -.. _doxygen-docs: - -* ``doxygen_docs``: [ ``'yes'`` | ``'no'`` ] - Build HTML documentation for the C++ interface using Doxygen. - - - default: ``'no'`` - -.. _sphinx-docs: - -* ``sphinx_docs``: [ ``'yes'`` | ``'no'`` ] - Build HTML documentation for Cantera using Sphinx. - - - default: ``'no'`` - -.. _sphinx-cmd: - -* ``sphinx_cmd``: [ ``path/to/sphinx_cmd`` ] - Command to use for building the Sphinx documentation. - - - default: ``'sphinx-build'`` - -.. _sphinx-options: - -* ``sphinx_options``: [ ``string`` ] - Options passed to the ``sphinx_cmd`` command line. Separate multiple - options with spaces, for example, ``"-W --keep-going"``. - - - default: ``'-W --keep-going'`` - -.. _system-eigen: - -* ``system_eigen``: [ ``'n'`` | ``'y'`` | ``'default'`` ] - Select whether to use Eigen from a system installation (``y``), from a - Git submodule (``n``), or to decide automatically (``default``). If Eigen - is not installed directly into a system include directory, for example, it - is installed in ``/opt/include/eigen3/Eigen``, then you will need to add - ``/opt/include/eigen3`` to ``extra_inc_dirs``. - - - default: ``'default'`` - -.. _system-fmt: - -* ``system_fmt``: [ ``'n'`` | ``'y'`` | ``'default'`` ] - Select whether to use the fmt library from a system installation - (``y``), from a Git submodule (``n``), or to decide automatically - (``default``). If you do not want to use the Git submodule and fmt - is not installed directly into system include and library - directories, then you will need to add those directories to - ``extra_inc_dirs`` and ``extra_lib_dirs``. This installation of fmt - must include the shared version of the library, for example, - ``libfmt.so``. - - - default: ``'default'`` - -.. _hdf-support: - -* ``hdf_support``: [ ``'n'`` | ``'y'`` | ``'default'`` ] - Select whether to support HDF5 container files natively (``y``), disable HDF5 - support (``n``), or to decide automatically based on the system configuration - (``default``). Native HDF5 support uses the HDF5 library as well as the - header-only HighFive C++ wrapper (see option ``system_highfive``). Specifying - ``hdf_include`` or ``hdf_libdir`` changes the default to ``y``. - - - default: ``'default'`` - -.. _hdf-include: - -* ``hdf_include``: [ ``path/to/hdf_include`` ] - The directory where the HDF5 header files are installed. This should be the - directory that contains files ``H5Version.h`` and ``H5Public.h``, amongst others. - Not needed if the headers are installed in a standard location, for example, - ``/usr/include``. - - - default: ``''`` - -.. _hdf-libdir: - -* ``hdf_libdir``: [ ``path/to/hdf_libdir`` ] - The directory where the HDF5 libraries are installed. Not needed if the - libraries are installed in a standard location, for example, ``/usr/lib``. - - - default: ``''`` - -.. _system-highfive: - -* ``system_highfive``: [ ``'n'`` | ``'y'`` | ``'default'`` ] - Select whether to use HighFive from a system installation (``y``), from a - Git submodule (``n``), or to decide automatically (``default``). If HighFive - is not installed directly into a system include directory, for example, it - is installed in ``/opt/include/HighFive``, then you will need to add - ``/opt/include/HighFive`` to ``extra_inc_dirs``. - - - default: ``'default'`` - -.. _system-yamlcpp: - -* ``system_yamlcpp``: [ ``'n'`` | ``'y'`` | ``'default'`` ] - Select whether to use the yaml-cpp library from a system installation - (``y``), from a Git submodule (``n``), or to decide automatically - (``default``). If yaml-cpp is not installed directly into system - include and library directories, then you will need to add those - directories to ``extra_inc_dirs`` and ``extra_lib_dirs``. - - - default: ``'default'`` - -.. _system-sundials: - -* ``system_sundials``: [ ``'n'`` | ``'y'`` | ``'default'`` ] - Select whether to use SUNDIALS from a system installation (``y``), from - a Git submodule (``n``), or to decide automatically (``default``). - Specifying ``sundials_include`` or ``sundials_libdir`` changes the - default to ``y``. - - - default: ``'default'`` - -.. _sundials-include: - -* ``sundials_include``: [ ``path/to/sundials_include`` ] - The directory where the SUNDIALS header files are installed. This - should be the directory that contains the ``"cvodes"``, ``"nvector"``, etc. - subdirectories. Not needed if the headers are installed in a - standard location, for example, ``/usr/include``. - - - default: ``''`` - -.. _sundials-libdir: - -* ``sundials_libdir``: [ ``path/to/sundials_libdir`` ] - The directory where the SUNDIALS static libraries are installed. - Not needed if the libraries are installed in a standard location, - for example, ``/usr/lib``. - - - default: ``''`` - -.. _system-blas-lapack: - -* ``system_blas_lapack``: [ ``'n'`` | ``'y'`` | ``'default'`` ] - Select whether to use BLAS/LAPACK from a system installation (``y``), use - Eigen linear algebra support (``n``), or to decide automatically based on - libraries detected on the system (``default``). Specifying ``blas_lapack_libs`` - or ``blas_lapack_dir`` changes the default to ``y``, whereas installing the - Matlab toolbox changes the default to ``n``. On macOS, the ``default`` option - uses the Accelerate framework, whereas on other operating systems the - preferred option depends on the CPU manufacturer. In general, OpenBLAS - (``openblas``) is prioritized over standard libraries (``lapack,blas``), with - Eigen being used if no suitable BLAS/LAPACK libraries are detected. On Intel - CPU's, MKL (Windows: ``mkl_rt`` / Linux: ``mkl_rt,dl``) has the highest priority, - followed by the other options. Note that Eigen is required whether or not - BLAS/LAPACK libraries are used. - - - default: ``'default'`` - -.. _blas-lapack-libs: - -* ``blas_lapack_libs``: [ ``string`` ] - Cantera can use BLAS and LAPACK libraries installed on your system if you - have optimized versions available (see option ``system_blas_lapack``). To use - specific versions of BLAS and LAPACK, set ``blas_lapack_libs`` to the the list - of libraries that should be passed to the linker, separated by commas, for - example, ``"lapack,blas"`` or ``"lapack,f77blas,cblas,atlas"``. - - - default: ``''`` - -.. _blas-lapack-dir: - -* ``blas_lapack_dir``: [ ``path/to/blas_lapack_dir`` ] - Directory containing the libraries specified by ``blas_lapack_libs``. Not - needed if the libraries are installed in a standard location, for example, - ``/usr/lib``. - - - default: ``''`` - -.. _lapack-ftn-trailing-underscore: - -* ``lapack_ftn_trailing_underscore``: [ ``'yes'`` | ``'no'`` ] - Controls whether the LAPACK functions have a trailing underscore - in the Fortran libraries. - - - default: ``'yes'`` - -.. _lapack-ftn-string-len-at-end: - -* ``lapack_ftn_string_len_at_end``: [ ``'yes'`` | ``'no'`` ] - Controls whether the LAPACK functions have the string length - argument at the end of the argument list (``yes``) or after - each argument (``no``) in the Fortran libraries. - - - default: ``'yes'`` - -.. _googletest: - -* ``googletest``: [ ``'default'`` | ``'system'`` | ``'submodule'`` | ``'none'`` ] - Select whether to use gtest/gmock from system - installation (``system``), from a Git submodule (``submodule``), to decide - automatically (``default``) or don't look for gtest/gmock (``none``) - and don't run tests that depend on gtest/gmock. - - - default: ``'default'`` - -.. _env-vars: - -* ``env_vars``: [ ``string`` ] - Environment variables to propagate through to SCons. Either the - string ``all`` or a comma separated list of variable names, for example, - ``LD_LIBRARY_PATH,HOME``. - - - default: ``'PATH,LD_LIBRARY_PATH,DYLD_LIBRARY_PATH,PYTHONPATH,USERPROFILE'`` - -.. _use-pch: - -* ``use_pch``: [ ``'yes'`` | ``'no'`` ] - Use a precompiled-header to speed up compilation - - - default: compiler dependent - - - If using ``ICC``: ``'no'`` - - Otherwise: ``'yes'`` - -.. _pch-flags: - -* ``pch_flags``: [ ``string`` ] - Compiler flags when using precompiled-header. - - - default: compiler dependent - - - If using ``MSVC``: ``'/FIpch/system.h'`` - - If using ``GCC``: ``'-include src/pch/system.h'`` - - If using ``icx``: ``'-include-pch src/pch/system.h.gch'`` - - If using ``Clang``: ``'-include-pch src/pch/system.h.gch'`` - - Otherwise: ``''`` - -.. _thread-flags: - -* ``thread_flags``: [ ``string`` ] - Compiler and linker flags for POSIX multithreading support. - - - default: platform dependent - - - Windows: ``''`` - - macOS: ``''`` - - Otherwise: ``'-pthread'`` - -.. _optimize: - -* ``optimize``: [ ``'yes'`` | ``'no'`` ] - Enable extra compiler optimizations specified by the - ``optimize_flags`` variable, instead of the flags specified by the - ``no_optimize_flags`` variable. - - - default: ``'yes'`` - -.. _optimize-flags: - -* ``optimize_flags``: [ ``string`` ] - Additional compiler flags passed to the C/C++ compiler when ``optimize=yes``. - - - default: compiler dependent - - - If using ``MSVC``: ``'/O2'`` - - If using ``ICC``: ``'-O3 -fp-model precise'`` - - If using ``icx``: ``'-O3 -fp-model precise'`` - - If using ``GCC``: ``'-O3 -Wno-inline'`` - - Otherwise: ``'-O3'`` - -.. _no-optimize-flags: - -* ``no_optimize_flags``: [ ``string`` ] - Additional compiler flags passed to the C/C++ compiler when ``optimize=no``. - - - default: compiler dependent - - - If using ``MSVC``: ``'/Od /Ob0'`` - - Otherwise: ``'-O0'`` - -.. _debug: - -* ``debug``: [ ``'yes'`` | ``'no'`` ] - Enable compiler debugging symbols. - - - default: ``'yes'`` - -.. _debug-flags: - -* ``debug_flags``: [ ``string`` ] - Additional compiler flags passed to the C/C++ compiler when ``debug=yes``. - - - default: compiler dependent - - - If using ``MSVC``: ``'/Zi /Fd${TARGET}.pdb'`` - - Otherwise: ``'-g'`` - -.. _no-debug-flags: - -* ``no_debug_flags``: [ ``string`` ] - Additional compiler flags passed to the C/C++ compiler when ``debug=no``. - - - default: ``''`` - -.. _debug-linker-flags: - -* ``debug_linker_flags``: [ ``string`` ] - Additional options passed to the linker when ``debug=yes``. - - - default: compiler dependent - - - If using ``MSVC``: ``'/DEBUG'`` - - Otherwise: ``''`` - -.. _no-debug-linker-flags: - -* ``no_debug_linker_flags``: [ ``string`` ] - Additional options passed to the linker when ``debug=no``. - - - default: ``''`` - -.. _warning-flags: - -* ``warning_flags``: [ ``string`` ] - Additional compiler flags passed to the C/C++ compiler to enable - extra warnings. Used only when compiling source code that is part - of Cantera (for example, excluding code in the ``ext`` directory). - - - default: compiler dependent - - - If using ``MSVC``: ``'/W3'`` - - Otherwise: ``'-Wall'`` - -.. _extra-inc-dirs: - -* ``extra_inc_dirs``: [ ``string`` ] - Additional directories to search for header files, with multiple - directories separated by colons (\*nix, macOS) or semicolons (Windows). - If an active ``conda`` environment is detected, the corresponding include - path is automatically added. - - - default: ``''`` - -.. _extra-lib-dirs: - -* ``extra_lib_dirs``: [ ``string`` ] - Additional directories to search for libraries, with multiple - directories separated by colons (\*nix, macOS) or semicolons (Windows). - If an active ``conda`` environment is detected, the corresponding library - path is automatically added. - - - default: ``''`` - -.. _boost-inc-dir: - -* ``boost_inc_dir``: [ ``path/to/boost_inc_dir`` ] - Location of the Boost header files. Not needed if the headers are - installed in a standard location, for example, ``/usr/include``. - - - default: ``''`` - -.. _stage-dir: - -* ``stage_dir``: [ ``path/to/stage_dir`` ] - Directory relative to the Cantera source directory to be - used as a staging area for building for example, a Debian - package. If specified, 'scons install' will install files - to ``stage_dir/prefix/...``. - - - default: ``''`` - -.. _verbose: - -* ``VERBOSE``: [ ``'yes'`` | ``'no'`` ] - Create verbose output about what SCons is doing. Deprecated in Cantera 3.0 - and to be removed thereafter; replaceable by ``logging=debug``. - - - default: ``'no'`` - -.. _logging: - -* ``logging``: [ ``'debug'`` | ``'info'`` | ``'warning'`` | ``'error'`` | ``'default'`` ] - Select logging level for SCons output. By default, logging messages use - the ``info`` level for 'scons build' and the ``warning`` level for all other - commands. In case the SCons option ``--silent`` is passed, all messages below - the ``error`` level are suppressed. - - - default: ``'default'`` - -.. _gtest-flags: - -* ``gtest_flags``: [ ``string`` ] - Additional options passed to each GTest test suite, for example, - ``--gtest_filter=*pattern*``. Separate multiple options with spaces. - - - default: ``''`` - -.. _renamed-shared-libraries: - -* ``renamed_shared_libraries``: [ ``'yes'`` | ``'no'`` ] - If this option is turned on, the shared libraries that are created - will be renamed to have a ``_shared`` extension added to their base name. - If not, the base names will be the same as the static libraries. - In some cases this simplifies subsequent linking environments with - static libraries and avoids a bug with using valgrind with - the ``-static`` linking flag. - - - default: ``'yes'`` - -.. _versioned-shared-library: - -* ``versioned_shared_library``: [ ``'yes'`` | ``'no'`` ] - If enabled, create a versioned shared library, with symlinks to the - more generic library name, for example, ``libcantera_shared.so.2.5.0`` as the - actual library and ``libcantera_shared.so`` and ``libcantera_shared.so.2`` - as symlinks. - - - default: compiler dependent - - - If using ``mingw``: ``'no'`` - - If using ``MSVC``: ``'no'`` - - Otherwise: ``'yes'`` - -.. _use-rpath-linkage: - -* ``use_rpath_linkage``: [ ``'yes'`` | ``'no'`` ] - If enabled, link to all shared libraries using ``rpath``, that is, a fixed - run-time search path for dynamic library loading. - - - default: ``'yes'`` - -.. _openmp-flag: - -* ``openmp_flag``: [ ``string`` ] - Compiler flags used for multiprocessing (only used to generate sample build - scripts). - - - default: compiler dependent - - - If using ``MSVC``: ``'/openmp'`` - - If using ``ICC``: ``'-qopenmp'`` - - If using ``icx``: ``'-qopenmp'`` - - If using ``apple-clang``: ``'-Xpreprocessor -fopenmp'`` - - Otherwise: ``'-fopenmp'`` - -.. _layout: - -* ``layout``: [ ``'standard'`` | ``'compact'`` | ``'conda'`` ] - The layout of the directory structure. ``standard`` installs files to - several subdirectories under 'prefix', for example, ``prefix/bin``, - ``prefix/include/cantera``, ``prefix/lib`` etc. This layout is best used in - conjunction with ``"prefix='/usr/local'"``. ``compact`` puts all installed files - in the subdirectory defined by 'prefix'. This layout is best with a prefix - like ``/opt/cantera``. If the Python executable found during compilation is - managed by ``conda``, the layout will default to ``conda`` irrespective of - operating system. For the ``conda`` layout, the Python package as well as all - libraries and header files are installed into the active ``conda`` environment. - Input data, samples, and other files are installed in the ``shared/cantera`` - subdirectory of the active ``conda`` environment. - - - default: platform dependent - - - Windows: ``'compact'`` - - Otherwise: ``'standard'`` - -.. _package-build: - -* ``package_build``: [ ``'yes'`` | ``'no'`` ] - Used in combination with packaging tools (example: ``conda-build``). If - enabled, the installed package will be independent from host and build - environments, with all external library and include paths removed. Packaged - C++ and Fortran samples assume that users will compile with local SDKs, which - should be backwards compatible with the tools used for the build process. - - - default: ``'no'`` - -.. _fast-fail-tests: - -* ``fast_fail_tests``: [ ``'yes'`` | ``'no'`` ] - If enabled, tests will exit at the first failure. - - - default: ``'no'`` - -.. _skip-slow-tests: - -* ``skip_slow_tests``: [ ``'yes'`` | ``'no'`` ] - If enabled, skip a subset of tests that are known to have long runtimes. - Skipping these may be desirable when running with options that cause tests - to run slowly, like disabling optimization or activating code profiling. - - - default: ``'no'`` - -.. _show-long-tests: - -* ``show_long_tests``: [ ``'yes'`` | ``'no'`` ] - If enabled, duration of slowest tests will be shown. - - - default: ``'no'`` - -.. _verbose-tests: - -* ``verbose_tests``: [ ``'yes'`` | ``'no'`` ] - If enabled, verbose test output will be shown. - - - default: ``'no'`` diff --git a/pages/compiling/source-code.rst b/pages/compiling/source-code.rst deleted file mode 100644 index b83743dfb..000000000 --- a/pages/compiling/source-code.rst +++ /dev/null @@ -1,131 +0,0 @@ -.. title: Downloading the Cantera source code - -.. _sec-source-code: - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Downloading the Cantera source code</h1> - - -Stable Release --------------- - -* **Option 1**: Check out the code using Git (recommended): - - .. code:: bash - - git clone --recursive https://github.com/Cantera/cantera.git - cd cantera - - Then, check out the tag of the most recent stable version: - - .. code:: bash - - git checkout tags/v3.0.0 - git submodule update - - A list of all the tags can be shown by: - - .. code:: bash - - git tag --list - -* **Option 2**: Download the most recent source ``.tar.gz`` or ``.zip`` file - from `Github <https://github.com/Cantera/cantera/releases>`__ and extract the - contents. In this case, several dependencies that are linked to the Cantera Git - repository will not be available and will need to be installed elsewhere on your - system. - -Beta Release ------------- - -* Check out the code using Git: - - .. code:: bash - - git clone --recursive https://github.com/Cantera/cantera.git - cd cantera - - Then pick either **Option 1** or **Option 2** below. - -* **Option 1**: Check out the tag with the most recent beta release: - - .. code:: bash - - git checkout tags/v3.0.0b1 - git submodule update - - Note that the most recent beta version might be older than the most recent - stable release. A list of all the tags, including stable and beta versions can - be shown by: - - .. code:: bash - - git tag --list - -* **Option 2**: Check out the branch with all the bug fixes leading to the - next minor release of the stable version: - - .. code:: bash - - git checkout 3.0 - git submodule update - - This branch has all the work on the 3.0.x version of the software. - - If you've already checked out the 3.0 branch, you can get the latest updates from the - main Cantera repository and synchronize your local repository by running: - - .. code:: bash - - git checkout 3.0 - git fetch --all - git pull --ff-only - -Development Version -------------------- - -Check out the code using Git: - -.. code:: bash - - git clone --recursive https://github.com/Cantera/cantera.git - cd cantera - -Note that by default, the ``main`` branch is checked out, containing all of -the feature updates and bug fixes to the code since the previous stable release. -The main branch is usually an alpha release, corresponding to the ``a`` in -the version number, and does not usually get a tag. - -If you've previously checked out the repository, and haven't made any changes locally, -you can get the latest updates from the main Cantera repository and synchronize your -local repository by running: - -.. code:: bash - - git checkout main - git fetch --all - git pull --ff-only - -.. container:: container - - .. container:: row - - .. container:: col-6 text-left - - .. container:: btn btn-primary - :tagname: a - :attributes: href=compilation-reqs.html - - Previous: Compilation Requirements - - - .. container:: col-6 text-right - - .. container:: btn btn-primary - :tagname: a - :attributes: href=configure-build.html - - Next: Configure & Build diff --git a/pages/compiling/special-cases.rst b/pages/compiling/special-cases.rst deleted file mode 100644 index 9f8ccabbf..000000000 --- a/pages/compiling/special-cases.rst +++ /dev/null @@ -1,96 +0,0 @@ -.. title: Special Compiling Cases - -.. _sec-special-compiling-cases: - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Special Compiling Cases</h1> - - .. class:: lead - - This guide explains some of the less common ways to build Cantera - -.. _conda-build: - -Building the Conda Package -========================== - -* The recipe for the Cantera Conda package is located at https://github.com/Cantera/conda-recipes - -* See the ``README.md`` in that repository for instructions. - -.. _sec-intel-compilers: - -Intel Compilers -=============== - -* The following instructions refer to the `Intel OneAPI Toolkit - <https://www.intel.com/content/www/us/en/developer/tools/oneapi/toolkits.html>`__. - -* Before compiling Cantera, you may need to set up the appropriate environment - variables for the Intel compiler suite. For example: - - .. code:: bash - - source /opt/intel/oneapi/setvars.sh - -* For the Intel compiler to work with SCons, these environment variables need - to be passed through SCons by using the command line option: - - .. code:: bash - - env_vars=all - -* If you want to use the Intel MKL versions of BLAS and LAPACK, you will need - to provide additional options. The following are typically correct on - 64-bit Linux systems: - - .. code:: bash - - blas_lapack_libs=mkl_rt blas_lapack_dir=$(MKLROOT)/lib/intel64 - - Your final SCons call might then look something like: - - .. code:: bash - - scons build env_vars=all CC=icx CXX=icpx FORTRAN=ifx blas_lapack_libs=mkl_rt blas_lapack_dir=$(MKLROOT)/lib/intel64 - -* When installing Cantera after building with the Intel compiler, the normal - method of using ``sudo`` to install Cantera to the system default directories - will not work because ``sudo`` does not pass the environment variables needed - by the Intel compiler. Instead, you will need to do something like: - - .. code:: bash - - scons build ... - sudo -s - source /path/to/setvars.sh - scons install - exit - - Another option is to set the :ref:`prefix <prefix>` option to a directory - for which you have write permissions, and specify the ``USER`` value to the - :ref:`python_prefix <python-prefix>` option. - -.. container:: container - - .. container:: row - - .. container:: col-6 text-left - - .. container:: btn btn-primary - :tagname: a - :attributes: href=dependencies.html - - Previous: Dependencies - - - .. container:: col-6 text-right - - .. container:: btn btn-primary - :tagname: a - :attributes: href=config-options.html - - Next: Configuration Options diff --git a/pages/dave-goodwin.rst b/pages/dave-goodwin.rst deleted file mode 100644 index 6817b41c0..000000000 --- a/pages/dave-goodwin.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. title: Dave Goodwin -.. description: Memorial page for Cantera's creator, Dave Goodwin -.. slug: dave - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">In Memoriam: Dave Goodwin</h1> - -.. image:: images/dave-goodwin.jpg - :alt: Dave Goodwin - :align: right - :scale: 75 - -.. class:: lead - - Prof. David Goodwin, Original Developer of Cantera - - *1957–2012* - -*"Keep on working to make this world a better place. It is important to get your thoughts away from your problems and focused on those who are less fortunate than you are."* - -*"We can't control the hand of cards we are dealt, but we sure can determine how we play them."* - -Dave Goodwin, the original developer of Cantera, passed away in 2012. We would like to provide this page for his friends and colleagues to salute his efforts at developing an open-source constitutive modeling package. Caltech also wrote a `lengthy article about Dave's life and work <http://www.caltech.edu/news/caltech-mourns-passing-david-g-goodwin-37485>`__. Please submit your thoughts and remembrances about Dave for inclusion on this page. - ------------- - -The Origin of Cantera -~~~~~~~~~~~~~~~~~~~~~ - -I know that the development of Cantera was a real passion for Dave, an advocacy for which went way beyond just his normal professional life. I think that whole community owes Dave a debt of gratitude in getting Cantera off of the ground and that the debt is best paid by continuing to develop Cantera along the principles that he so fervently espoused. - -Dave started off by with an extensive overhaul of the Chemkin suite of programs for gas-phase thermochemistry and kinetics. Chemkin had originally been developed at Sandia National Laboratories in the 1970s and had quickly gone into worldwide use. Dave became interested in overhauling Chemkin for two primary reasons. The first reason was that, mostly because of its success, Chemkin became a for-profit product whose distribution rights was licensed out during the nineties. Dave was very passionate about the open-source movement and about the necessity of keeping software for academic use as being in the public domain. Dave chose Cantera's licensing approach, Berkeley license, with this in mind. - -The second reason was that Dave saw the need to upgrade the modeling software to an object-oriented structure, which could then be extended easily to new constitutive models and situations. Dave had a strong passion for making sure his software kept up with the times, and advocated for the current multi-interface structure that Cantera currently has. Along the way he developed a new formalism for calculating the collision integrals used in the evaluation of transport parameters from dilute ideal gases theory. - -I first became aware of Dave's contributions through his groundbreaking work on diamond CVD. I remember reading his papers on the subject and marveling at how understanding the detailed kinetics of surface processes could directly lead to a real understanding of the performance of diamond growth reactors. That work probably was done with Cantera, and probably helped to direct the structure and content of Dave's original formulation of Cantera. - -| Best wishes, -| Harry Moffat - ------------- - -A couple Christmas seasons before Dave died, we were visiting in his home. One side of his body was paralyzed by a glioma, the other side gripped by Parkinson's. I asked Dave if he was bitter about his infirmity. He simply said, “I’ve got no time for anger.” The next Christmas I was thinking about Dave's paintings. Many hung in his living room, and there was one I remembered in his grad school office that Richard Diebenkorn would have been proud to sign. Dave's home is a few minutes from the Norton-Simon art museum. Impromptu Dave, Frances, and I threw the wheel chair in the trunk, and went. A big storm had just felled a large tree in the sculpture garden. Frances' manner impressed me. Perhaps ancient wisdom or medical training enabled her to at once care for Dave and treat him as an independent equal. Dave and Frances brought equanimity to life’s rewards and responsibilities. Much thanks. You are in our hearts. - -smjaffe11, Dec 6, 2012 - ------------- - -Dave was my co-advisor during my PhD work at Caltech from 1997-2002, and I benefitted greatly from my weekly meetings with him. His work on developing Cantera was an integral part of the modeling component to my thesis on polycrystalline silicon CVD, but more broadly his effort to democratize this information has proven to be hugely valuable to a number of communities. While I no longer work in this space since leaving Caltech, I sincerely hope that other researchers for whom this package is valuable continue to make contributions and refinements. Dave will be greatly missed and my thoughts are with his family. - -jasonkholt, Dec 13, 2012 diff --git a/pages/documentation/dev-docs.html b/pages/documentation/dev-docs.html deleted file mode 100644 index 06cec6d52..000000000 --- a/pages/documentation/dev-docs.html +++ /dev/null @@ -1,130 +0,0 @@ -<!-- -.. title: Cantera Developerment Version Documentation -.. slug: dev-docs -.. date: 2018-06-09 13:57:46 UTC-04:00 -.. description: API documentation for the Cantera interfaces -.. type: text ---> - -<div class="jumbotron"> - <h1 class="display-4">Development Version Documentation</h1> - <p class="lead"> - This documentation is for the Development Version of Cantera. If you built Cantera yourself from - the <code>main</code> branch, this documentation describes any changes that have been made - since the last release. - </p> - - <div id="searchbox" style="display: inline-block" role="search"> - <h3>Search the documentation</h3> - <div class="searchformwrapper"> - <form class="search" action="{{% ct_dev_docs search.html %}}" method="get"> - <input type="text" name="q" size="50" /> - <input type="submit" value="Go" /> - <input type="hidden" name="check_keywords" value="yes" /> - <input type="hidden" name="area" value="default" /> - </form> - </div> - </div> -</div> - -<div class="row"> - <div class="col-sm-6"> - <div class="card" id="python-docs"> - <div class="card-header section-card"> - Python - </div> - <div class="list-group list-group-flush"> - <a href="{{% ct_dev_docs python/importing.html %}}" class="list-group-item dev-docs"> - Objects Representing Phases (<code>Solution</code>s, <code>PureFluid</code>s, <code>Interface</code>s, etc.) - </a> - <a href="{{% ct_dev_docs python/thermo.html %}}" class="list-group-item dev-docs"> - Thermodynamic Properties (Temperature, pressure, energy, etc.) - </a> - <a href="{{% ct_dev_docs python/kinetics.html %}}" class="list-group-item dev-docs"> - Chemical Kinetics (Reactions, rates of progress, reaction path analysis, etc.) - </a> - <a href="{{% ct_dev_docs python/transport.html %}}" class="list-group-item dev-docs"> - Transport Properties (Diffusion, viscosity, thermal conductivity, etc.) - </a> - <a href="{{% ct_dev_docs python/zerodim.html %}}" class="list-group-item dev-docs"> - Zero-Dimensional Reactor Networks (<code>Reactor</code>s, <code>IdealGasReactor</code>s, <code>Wall</code>s, etc.) - </a> - <a href="{{% ct_dev_docs python/onedim.html %}}" class="list-group-item dev-docs"> - One-dimensional Reacting Flows (<code>FreeFlame</code>s, <code>BurnerFlame</code>s, Flow Domains, Boundaries, etc.) - </a> - <a href="{{% ct_dev_docs python/constants.html %}}" class="list-group-item dev-docs"> - Physical Constants (Universal constants, built into Cantera for convenience) - </a> - </div> - </div> - </div> - <div class="col-sm-6"> - <div class="card" id="matlab-docs"> - <div class="card-header section-card"> - Matlab - </div> - <div class="list-group list-group-flush"> - <a href="{{% ct_dev_docs matlab/importing.html %}}" class="list-group-item dev-docs"> - Objects Representing Phases (<code>Solution</code>s, <code>PureFluid</code>s, <code>Interface</code>s, etc.) - </a> - <a href="{{% ct_dev_docs matlab/thermodynamics.html %}}" class="list-group-item dev-docs"> - Thermodynamic Properties (Temperature, pressure, energy, etc.) - </a> - <a href="{{% ct_dev_docs matlab/kinetics.html %}}" class="list-group-item dev-docs"> - Chemical Kinetics (Reactions, rates of progress, reaction path analysis, etc.) - </a> - <a href="{{% ct_dev_docs matlab/transport.html %}}" class="list-group-item dev-docs"> - Transport Properties (Diffusion, viscosity, thermal conductivity, etc.) - </a> - <a href="{{% ct_dev_docs matlab/zero %}}-dim.html" class="list-group-item dev-docs"> - Zero-Dimensional Reactor Networks (<code>Reactor</code>s, <code>IdealGasReactor</code>s, <code>Wall</code>s, etc.) - </a> - <a href="{{% ct_dev_docs matlab/one %}}-dim.html" class="list-group-item dev-docs"> - One-dimensional Reacting Flows (<code>FreeFlame</code>s, <code>BurnerFlame</code>s, Flow Domains, Boundaries, etc.) - </a> - <a href="{{% ct_dev_docs matlab/data.html %}}" class="list-group-item dev-docs"> - Physical Constants (Universal constants, built into Cantera for convenience) - </a> - <a href="{{% ct_dev_docs matlab/utilities.html %}}" class="list-group-item dev-docs"> - Utility functions (data directory manipulation, version information, etc.) - </a> - </div> - </div> - </div> -</div> - -<div class="row"> - <div class="col-sm-6"> - <div class="card" id="cxx-docs"> - <div class="card-header section-card"> - C++ - </div> - <div class="list-group list-group-flush"> - <a href="{{% ct_dev_docs cxx/modules.html %}}" class="list-group-item dev-docs">List of Cantera Modules</a> - <a href="{{% ct_dev_docs cxx/classes.html %}}" class="list-group-item dev-docs">List of Cantera Classes</a> - <a href="{{% ct_dev_docs cxx/da/d58/deprecated.html %}}" class="list-group-item dev-docs">List of Deprecated Functions and Classes</a> - </div> - </div> - </div> - <div class="col-sm-6"> - <div class="card" id="other-docs"> - <div class="card-header section-card"> - Other Documentation - </div> - <div class="list-group list-group-flush"> - <a href="/tutorials/yaml/defining-phases.html" class="list-group-item dev-docs"> - YAML Input File Users' Guide - </a> - </div> - <div class="list-group list-group-flush"> - <a href="{{% ct_dev_docs yaml/index.html %}}" class="list-group-item dev-docs"> - YAML Input File API Reference - </a> - </div> - </div> - </div> -</div> - -<p class="text-center"> - <a href="/documentation/index.html" class="btn btn-lg btn-outline-primary">Go Back to the Current Documentation</a> -</p> diff --git a/pages/documentation/glossary.rst b/pages/documentation/glossary.rst deleted file mode 100644 index 51acb19f4..000000000 --- a/pages/documentation/glossary.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. title: Glossary -.. slug: glossary -.. description: Glossary of commonly used abbreviations in Cantera - -******** -Glossary -******** - -The following abbreviations are used in Cantera, both in documentation and in -the names of variables and classes: - -* **CK**: Chemkin -* **CT**: Cantera -* **CTI**: Cantera Input *(Removed in Cantera 3.0)* -* **CTML**: Cantera Markup Language *(Removed in Cantera 3.0)* -* **HKFT**: Helgeson-Kirkham-Flowers-Tanger -* **HMW**: Harvie, Møller, and Weare -* **IAPWS**: International Association for the Properties of Water and Steam -* **MFTP**: Mixture Fugacity ThermoPhase -* **PDSS**: Pressure-dependent standard state -* **RT**: Product of the gas constant (R) and the temperature -* **SHE**: Single half-electrode -* **SP**: Surface Problem -* **SS**: Standard state -* **SSTP**: SingleSpeciesTP (ThermoPhase) -* **STIT**: SpeciesThermoInterpType -* **VCS**: Villars Cruise Smith -* **VPSS**: Variable Pressure Standard State -* **VPSSTP**: Variable Pressure Standard State ThermoPhase -* **wrt**: with respect to diff --git a/pages/documentation/index.html b/pages/documentation/index.html deleted file mode 100644 index 5ca055b2b..000000000 --- a/pages/documentation/index.html +++ /dev/null @@ -1,188 +0,0 @@ -<!-- -.. title: Cantera Documentation -.. slug: index -.. date: 2018-06-09 13:57:46 UTC-04:00 -.. description: API documentation for the Cantera interfaces -.. type: text ---> - -<div class="jumbotron"> - <h1 class="display-4">Documentation</h1> - <p class="lead"> - Sometimes you just need a little more detail. You'll find documentation for - (almost) every function in Cantera right here. This is the documentation for - the current stable release, Cantera 3.0.0. For other versions, see the links - at the bottom of the page. - </p> - - <div id="searchbox" style="display: inline-block" role="search"> - <h3>Search the documentation</h3> - <div class="searchformwrapper"> - <form class="search" action="{{% ct_docs sphinx/html/search.html %}}" method="get"> - <input type="text" name="q" size="50" /> - <input type="submit" value="Go" /> - <input type="hidden" name="check_keywords" value="yes" /> - <input type="hidden" name="area" value="default" /> - </form> - </div> - </div> -</div> - -<div class="row"> - <div class="col-sm-6"> - <div class="card" id="python-docs"> - <div class="card-header section-card"> - Python - </div> - <div class="list-group list-group-flush"> - <a href="{{% ct_docs sphinx/html/cython/importing.html %}}" class="list-group-item docs"> - Objects Representing Phases (<code>Solution</code>s, <code>PureFluid</code>s, <code>Interface</code>s, etc.) - </a> - <a href="{{% ct_docs sphinx/html/cython/thermo.html %}}" class="list-group-item docs"> - Thermodynamic Properties (Temperature, pressure, energy, etc.) - </a> - <a href="{{% ct_docs sphinx/html/cython/kinetics.html %}}" class="list-group-item docs"> - Chemical Kinetics (Reactions, rates of progress, reaction path analysis, etc.) - </a> - <a href="{{% ct_docs sphinx/html/cython/transport.html %}}" class="list-group-item docs"> - Transport Properties (Diffusion, viscosity, thermal conductivity, etc.) - </a> - <a href="{{% ct_docs sphinx/html/cython/zerodim.html %}}" class="list-group-item docs"> - Zero-Dimensional Reactor Networks (<code>Reactor</code>s, <code>IdealGasReactor</code>s, <code>Wall</code>s, - etc.) - </a> - <a href="{{% ct_docs sphinx/html/cython/onedim.html %}}" class="list-group-item docs"> - One-dimensional Reacting Flows (<code>FreeFlame</code>s, <code>BurnerFlame</code>s, Flow Domains, Boundaries, - etc.) - </a> - <a href="{{% ct_docs sphinx/html/cython/constants.html %}}" class="list-group-item docs"> - Physical Constants (Universal constants, built into Cantera for convenience) - </a> - <a href="{{% ct_docs sphinx/html/cython/units.html %}}" class="list-group-item docs"> - Python Interface with Units - </a> - <a href="{{% ct_docs sphinx/html/cython/utilities.html %}}" class="list-group-item docs"> - Utilities: YAML input/output, unit conversions, global functions - </a> - </div> - </div> - </div> - <div class="col-sm-6"> - <div class="card" id="matlab-docs"> - <div class="card-header section-card"> - Matlab - </div> - <div class="list-group list-group-flush"> - <a href="{{% ct_docs sphinx/html/matlab/importing.html %}}" class="list-group-item docs"> - Objects Representing Phases (<code>Solution</code>s, <code>PureFluid</code>s, <code>Interface</code>s, etc.) - </a> - <a href="{{% ct_docs sphinx/html/matlab/thermodynamics.html %}}" class="list-group-item docs"> - Thermodynamic Properties (Temperature, pressure, energy, etc.) - </a> - <a href="{{% ct_docs sphinx/html/matlab/kinetics.html %}}" class="list-group-item docs"> - Chemical Kinetics (Reactions, rates of progress, reaction path analysis, etc.) - </a> - <a href="{{% ct_docs sphinx/html/matlab/transport.html %}}" class="list-group-item docs"> - Transport Properties (Diffusion, viscosity, thermal conductivity, etc.) - </a> - <a href="{{% ct_docs sphinx/html/matlab/zero %}}-dim.html" class="list-group-item docs"> - Zero-Dimensional Reactor Networks (<code>Reactor</code>s, <code>IdealGasReactor</code>s, <code>Wall</code>s, - etc.) - </a> - <a href="{{% ct_docs sphinx/html/matlab/one %}}-dim.html" class="list-group-item docs"> - One-dimensional Reacting Flows (<code>FreeFlame</code>s, <code>BurnerFlame</code>s, Flow Domains, Boundaries, - etc.) - </a> - <a href="{{% ct_docs sphinx/html/matlab/data.html %}}" class="list-group-item docs"> - Physical Constants (Universal constants, built into Cantera for convenience) - </a> - <a href="{{% ct_docs sphinx/html/matlab/utilities.html %}}" class="list-group-item docs"> - Utility functions (XML Parsers, conversion scripts, etc.) - </a> - </div> - </div> - </div> -</div> - -<div class="row"> - <div class="col-sm-6"> - <div class="card" id="cxx-docs"> - <div class="card-header section-card"> - C++ - </div> - <div class="list-group list-group-flush"> - <a href="{{% ct_docs doxygen/html/index.html %}}" class="list-group-item docs">Cantera C++ Reference</a> - <a href="{{% ct_docs doxygen/html/modules.html %}}" class="list-group-item docs">List of Cantera Modules</a> - <a href="{{% ct_docs doxygen/html/classes.html %}}" class="list-group-item docs">List of Cantera Classes</a> - <a href="{{% ct_docs doxygen/html/da/d58/deprecated.html %}}" class="list-group-item docs">List of Deprecated - Functions and Classes</a> - <a href="{{% ct_docs doxygen/html/d0/de3/citelist.html %}}" class="list-group-item docs">Bibliography</a> - </div> - </div> - </div> - <div class="col-sm-6"> - <div class="card" id="other-docs"> - <div class="card-header section-card"> - Other Documentation - </div> - <div class="list-group list-group-flush"> - <a href="/tutorials/yaml/defining-phases.html" class="list-group-item docs"> - YAML Input File Users' Guide - </a> - <a href="{{% ct_docs sphinx/html/yaml/index.html %}}" class="list-group-item docs"> - YAML Input File API Reference - </a> - <a href="/documentation/glossary.html" class="list-group-item docs">Glossary of Terms</a> - </div> - </div> - </div> -</div> - -<div class="jumbotron"> - <h2>Need something else?</h2> - <p class="lead"> - If you need documentation for the unreleased development version or older versions of Cantera, - you can find those here. Please note that older versions of Cantera are obsolete, and users are - strongly encouraged to migrate to the current version of Cantera. - </p> -</div> - -<div class="row"> - <div class="col-sm-6"> - <div class="card" id="dev-and-old-docs"> - <div class="card-header section-card"> - Development and Older Versions - </div> - <div class="list-group list-group-flush"> - <a href="/documentation/dev-docs.html" class="list-group-item dev-docs">Development Version</a> - <a href="docs-2.6/index.html" class="list-group-item dev-docs">Cantera 2.6.0</a> - <a href="docs-2.5/index.html" class="list-group-item dev-docs">Cantera 2.5.1</a> - <a href="docs-2.4/index.html" class="list-group-item dev-docs">Cantera 2.4.0</a> - <a href="docs-2.3/sphinx/html/index.html" class="list-group-item dev-docs">Cantera 2.3.0</a> - <a href="docs-2.2/sphinx/html/index.html" class="list-group-item dev-docs">Cantera 2.2.1</a> - <a href="docs-2.1/sphinx/html/index.html" class="list-group-item dev-docs">Cantera 2.1.2</a> - <a href="docs-2.0/sphinx/html/index.html" class="list-group-item dev-docs">Cantera 2.0.2</a> - </div> - </div> - </div> - <div class="col-sm-6"> - <div class="card"> - <div class="card-header section-card"> - Release Notes - </div> - <div class="list-group list-group-flush" id="release-notes"> - <a href="/documentation/release_notes/v3.0.0.html" class="list-group-item release-notes">Cantera 3.0.0</a> - <a href="/documentation/release_notes/v2.6.0.html" class="list-group-item release-notes">Cantera 2.6.0</a> - <a href="/documentation/release_notes/v2.5.1.html" class="list-group-item release-notes">Cantera 2.5.1</a> - <a href="/documentation/release_notes/v2.4.0.html" class="list-group-item release-notes">Cantera 2.4.0</a> - <a href="/documentation/release_notes/v2.3.0.html" class="list-group-item release-notes">Cantera 2.3.0</a> - <a href="/documentation/release_notes/v2.2.1.html" class="list-group-item release-notes">Cantera 2.2.1</a> - <a href="/documentation/release_notes/v2.2.0.html" class="list-group-item release-notes">Cantera 2.2.0</a> - <a href="/documentation/release_notes/v2.1.2.html" class="list-group-item release-notes">Cantera 2.1.2</a> - <a href="/documentation/release_notes/v2.1.1.html" class="list-group-item release-notes">Cantera 2.1.1</a> - <a href="/documentation/release_notes/v2.1.0.html" class="list-group-item release-notes">Cantera 2.1.0</a> - <a href="/documentation/release_notes/v2.0.2.html" class="list-group-item release-notes">Cantera 2.0.2</a> - </div> - </div> - </div> -</div> diff --git a/pages/documentation/release_notes/v2.0.2.md b/pages/documentation/release_notes/v2.0.2.md deleted file mode 100644 index b3338e544..000000000 --- a/pages/documentation/release_notes/v2.0.2.md +++ /dev/null @@ -1,16 +0,0 @@ -<!-- -.. title: Cantera 2.0.2 -.. slug: v2.0.2 -.. date: 2015-04-06T21:04:23Z -.. tags: -.. category: -.. link: -.. description: -.. type: text ---> - -# Cantera 2.0.2 - -Published on April 6, 2015 | [Full release on Github](https://github.com/Cantera/cantera/releases/tag/v2.0.2) - -- Maintenance release fixing issues identified in Cantera 2.0.1. diff --git a/pages/documentation/release_notes/v2.1.0.md b/pages/documentation/release_notes/v2.1.0.md deleted file mode 100644 index 3078fbfc8..000000000 --- a/pages/documentation/release_notes/v2.1.0.md +++ /dev/null @@ -1,27 +0,0 @@ -<!-- -.. title: Cantera 2.1.0 -.. slug: v2.1.0 -.. date: 2015-04-06T21:00:20Z -.. tags: -.. category: -.. link: -.. description: -.. type: text ---> - -# Cantera 2.1.0 - -Published on April 6, 2015 | [Full release on Github](https://github.com/Cantera/cantera/releases/tag/v2.1.0) - -Some of the major improvements since the release of Cantera 2.0 are: - -- A new Cython-based Python interface, with a streamlined API and support for Python 3.2 and higher (as well as Python 2.6 and 2.7) -- Reformulation of reactor governing equations to improve performance and robustness, especially for larger mechanisms, including the addition of reactor types specifically optimized for ideal gases -- Improved support for reactor network sensitivity analysis -- Support for "chemically activated" reaction rate parameterizations -- Better support for importing "Chemkin"-format mechanisms using ck2cti.py -- Numerous improvements to performance and robustness of the 1D solver -- More comprehensive save/restore feature for 1D simulations -- Test suite coverage of the 1D flame module -- Support for compilation using Visual Studio 2012 -- Extensive clean-up of Doxygen documentation diff --git a/pages/documentation/release_notes/v2.1.1.md b/pages/documentation/release_notes/v2.1.1.md deleted file mode 100644 index 1d83e5776..000000000 --- a/pages/documentation/release_notes/v2.1.1.md +++ /dev/null @@ -1,16 +0,0 @@ -<!-- -.. title: Cantera 2.1.1 -.. slug: v2.1.1 -.. date: 2015-04-06T20:56:02Z -.. tags: -.. category: -.. link: -.. description: -.. type: text ---> - -# Cantera 2.1.1 - -Published on April 6, 2015 | [Full release on Github](https://github.com/Cantera/cantera/releases/tag/v2.1.1) - -- Maintenance release fixing issues identified since Cantera 2.1.0. diff --git a/pages/documentation/release_notes/v2.1.2.md b/pages/documentation/release_notes/v2.1.2.md deleted file mode 100644 index 816410638..000000000 --- a/pages/documentation/release_notes/v2.1.2.md +++ /dev/null @@ -1,17 +0,0 @@ -<!-- -.. title: Cantera 2.1.2 -.. slug: v2.1.2 -.. date: 2015-04-06T20:53:32Z -.. tags: -.. category: -.. link: -.. description: -.. type: text ---> - -# Cantera 2.1.2 - -Published on April 6, 2015 | [Full release on Github](https://github.com/Cantera/cantera/releases/tag/v2.1.2) - -- Maintenance release fixing issues identified in Cantera 2.1.1. -- Now includes binaries for Python 3.4. diff --git a/pages/documentation/release_notes/v2.2.0.md b/pages/documentation/release_notes/v2.2.0.md deleted file mode 100644 index 3a689dd52..000000000 --- a/pages/documentation/release_notes/v2.2.0.md +++ /dev/null @@ -1,35 +0,0 @@ -<!-- -.. title: Cantera 2.2.0 -.. slug: v2.2.0 -.. date: 2015-06-05T16:47:35Z -.. tags: -.. category: -.. link: -.. description: -.. type: text ---> - -# Cantera 2.2.0 - -Published on June 5, 2015 | [Full release on Github](https://github.com/Cantera/cantera/releases/tag/v2.2.0) - -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](http://cantera.github.io/docs/sphinx/html/cython/examples/kinetics_extract_submechanism.html) and [mechanism_reduction.py](http://cantera.github.io/docs/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](http://cantera.github.io/docs/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](http://cantera.github.io/docs/sphinx/html/cython/examples/onedim_diffusion_flame.html). -- Efficient sensitivity analysis of 1D flame solutions (see [flamespeed_sensitivity.py](http://cantera.github.io/docs/sphinx/html/cython/examples/onedim_flamespeed_sensitivity.html)). -- Added strain rate calculations for diffusion flames (see [diffusion_flame_extinction.py](http://cantera.github.io/docs/sphinx/html/cython/examples/onedim_diffusion_flame_extinction.html) and [diffusion_flame_batch.py](http://cantera.github.io/docs/sphinx/html/cython/examples/onedim_diffusion_flame_batch.html)). -- Added premixed counterflow flame configuration to Python module (see [premixed_counterflow_flame.py](http://cantera.github.io/docs/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](http://cantera.github.io/docs/sphinx/html/matlab/index.html). - -**Downloads available:** - -- Source code (all platforms) - Download `cantera-2.2.0.tar.gz` below, and see the [compilation guide](http://cantera.github.io/docs/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](http://cantera.github.io/docs/sphinx/html/install.html#windows) for details. -- Ubuntu packages for Trusty (14.04 LTS), Utopic, and Vivid via a Launchpad PPA; see [installation instructions](http://cantera.github.io/docs/sphinx/html/install.html#ubuntu) -- OS X Homebrew formula; see [installation instructions](http://cantera.github.io/docs/sphinx/html/install.html#mac-os-x) diff --git a/pages/documentation/release_notes/v2.2.1.md b/pages/documentation/release_notes/v2.2.1.md deleted file mode 100644 index dab3ec1f2..000000000 --- a/pages/documentation/release_notes/v2.2.1.md +++ /dev/null @@ -1,17 +0,0 @@ -<!-- -.. title: Cantera 2.2.1 -.. slug: v2.2.1 -.. date: 2016-01-26T21:16:16Z -.. tags: -.. category: -.. link: -.. description: -.. type: text ---> - -# Cantera 2.2.1 - -Published on January 26, 2016 | [Full release on Github](https://github.com/Cantera/cantera/releases/tag/v2.2.1) - -- Maintenance release fixing issues identified since Cantera 2.2.0. -- Now includes Windows binaries for Python 3.5. diff --git a/pages/documentation/release_notes/v2.3.0.md b/pages/documentation/release_notes/v2.3.0.md deleted file mode 100644 index 979e9019e..000000000 --- a/pages/documentation/release_notes/v2.3.0.md +++ /dev/null @@ -1,55 +0,0 @@ -<!-- -.. title: Cantera 2.3.0 -.. slug: v2.3.0 -.. date: 2017-01-19T03:27:22Z -.. tags: -.. category: -.. link: -.. description: -.. type: text ---> - -# Cantera 2.3.0 - -Published on January 19, 2017 | [Full release on Github](https://github.com/Cantera/cantera/releases/tag/v2.3.0) - -## Installation Options - -- Conda / anaconda packages for Windows, Linux, and macOS via the `cantera` channel. See [installation instructions](http://cantera.github.io/docs/sphinx/html/install.html#conda) 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](http://cantera.github.io/docs/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](http://cantera.github.io/docs/sphinx/html/install.html#ubuntu). -- Homebrew formula for macOS. See [additonal instructions](http://cantera.github.io/docs/sphinx/html/install.html#homebrew). -- Download and compile the source code. Full instructions [here](http://cantera.github.io/docs/sphinx/html/compiling.html). - -## Documentation - -Documentation for Cantera 2.3.0 can be found at: http://cantera.github.io/docs/sphinx/html/index.html. - -## Changes in Cantera 2.3.0 - -Highlights are listed here. See the [full changelog](https://github.com/Cantera/cantera/pull/399#issuecomment-263736973) for more. - -- Add ability to modify species data for existing Phase objects -- Make species names case-preserving instead of case-sensitive, and allow colons in species names -- Add option for Motz & Wise correction to sticking reactions -- Implement enthalpy of formation sensitivity analysis for reactor networks -- Implement the Cython function `advance_to_steady_state` for reactor networks -- Eliminate most known 1D flame solver failures by improving Jacobian evaluation, and using better default initial grids and initial guesses -- Introduce 'auto' option to Sim1D.solve to automatically try multiple initial grids -- Generalize initial profile generation for diffusion flames for arbitrary fuel/oxidizer combinations -- Add general support for calculating adjoint sensitivities for 1D flames -- Add a Twin Premixed Counterflow Flame class and example -- Support conversion of surface mechanism files -- Provide better error message for problematic reaction and thermo entries when converting input files -- Add 'nonreactant_orders' option to allow non-reactant orders -- Allow adding species / reactions from Python -- Add new classes `Quantity` and `SolutionArray` to Python -- Make Python test suite runnable from an installed copy of the Python module -- Introduced Continuous Integration testing using Travis CI and AppVeyor -- Use Git submodules for Sundials, Eigen, Google Test, and libfmt if system versions are not installed -- 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 http://cantera.github.io/dev-docs/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 diff --git a/pages/documentation/release_notes/v2.4.0.md b/pages/documentation/release_notes/v2.4.0.md deleted file mode 100644 index 07dc8f7e0..000000000 --- a/pages/documentation/release_notes/v2.4.0.md +++ /dev/null @@ -1,260 +0,0 @@ -<!-- -.. title: Cantera 2.4.0 -.. slug: v2.4.0 -.. date: 2018-08-24T21:23:37Z -.. tags: -.. category: -.. link: -.. description: -.. type: text ---> - -# Cantera 2.4.0 - -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, @bryanwweber, @BangShiuh, @decaluwe, @wandadars, @jsantner, @arghdos, @rwest, @g3bk47, @awehrfritz, @band-a-prend, @vdevgan, @KyleLinevitchJr, and @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. - -Thanks to a small development grant from NumFOCUS (see more about NumFOCUS below), @bryanwweber and @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. - -Cantera is now officially part of NumFOCUS. NumFOCUS is a 501(c)3 nonprofit dedicated to supporting the open source scientific computing community. If you are interested in learning more about NumFOCUS, please visit their website at https://numfocus.org, or our website at https://cantera.org/community.html#donations. - -Cantera 2.4.0 is the last release that will be compatible with Python 2.7. Support for Python 2.7 from the Python Software Foundation will [end January 1, 2020](https://www.python.org/dev/peps/pep-0373/#maintenance-releases). Given the recent release cadence of Cantera, the next major version of Cantera will probably be released very close to that date, so we have made the decision to drop Python 2.7 support for Cantera 2.5.0 and higher. - -One notable change to the build requirements for Cantera 2.4.0 is that SCons 3.0.0 or higher must be used to compile the source code. This means that either Python 2 or Python 3 can be used to run SCons. In addition, there are now three options to handle building the Python interface, depending on whether the user wants to build for Python 2 or Python 3. Please check the documentation or run `scons help` for more information. - -## Summary of changes in Cantera 2.4.0 - -### Bugs fixed - -- Fix inconstencies and bugs in several `ThermoPhase` derived classes, including `PDSS_IdealGas`, `IonsFromNeutralVPSSTP`, `PDSS_IonsFromNeutral`, `PDSS_HKFT`, `LatticePhase`, `PDSS_SSVol`, `ConstDensityThermo`, and `PureFluidPhase` -- Preserve constant property pair when multiplying `Quantity` objects -- Fix using pure fluids in reactors -- Add temperature dependence of rotational relaxation in transport calculations -- Disable linking to external SUNDIALS libraries when building the Matlab toolbox - -### Changes to existing capabilities - -- Allow instantiation of ThermoPhase derived classes without XML -- `set_equivalence_ratio` now supports sulfur oxidation -- Make all complex object types (ThermoPhase, Kinetics, Transport, Reactor, Domain1D, etc.) objects non-copyable -- Deprecate `FreeFlow` and `AxiStagnFlow` classes by moving the relevant functions into the `StFlow` class -- Allow `convertMech` function to be called multiple times -- Remove the requirement for users to have Boost headers installed when building against the Cantera library -- Change the options to build the Python interface, since SCons can be run by Python 3 -- Update GTest, fmtlib, SUNDIALS, and Eigen submodule versions - -### Additions - -- Add ion gas transport model, and `IonFlow` and `BurnerIonFlame` flame classes -- Add C++ OpenMP, Non-Ideal Shock Tube, PSR/WSR, and time-dependent mass flow rate examples -- Add class `AnyMap` -- Allow negative reaction orders -- Add unity Lewis number transport model -- Add electron to the built-in elements -- Add `get_equivalence_ratio` function - -# Full Changelog - -## Bugs fixed - -### Thermo/Species/Elements -- Fix issues parsing composition strings with mixtures of commas, colons, and spaces (3f6f580b25602ebb442769cca1ecf8f5d6818185) -- Fix setting mass/mole fractions of phases with only a single species (ed8de04e5b9a490b057d38fa8538c6091bfca92b) -- Fix reference state calculations (38d291c683046e41c4c40b194c27c9fef68be8b8, 7b529ac2d6a1332f852edeb31498c7ee5b2a88fb) -- Fix test failures due to inconsistent species addition order (11a0727d5ca6172fcb3596dbc11e7f7b1cc2e806, #433) -- Fix errors in entropy calculation in `PDSS_IdealGas` (dfb32f0c7ec0e5f037cb1879a73fcb926c8a401a) -- Fix and test creation of `IonsFromNeutralVPSSTP` objects (3a119381e81778d67a9ec83e6981d0050c620300) -- Fix inconsistentices in `PDSS_IonsFromNeutral` (ff46dc93b514d646cccf359e807cfb57ad68a460) -- Fix `PDSS_HKFT` initialization when only one property is given (2c3512c22a688ab8daecea751add0410e626fa5d) -- Fix default molar volume in `LatticePhase` (f3ba29f0bcfacc85cfd069d83626f46dcb0421c6) -- Setting the composition with an empty array raises an exception (8a4142d4bc33de089220b1e26282500c6ce2d02b) -- Fix implementation and documentation of `PDSS_SSVol` (ee663c9b3772be84f740a3b36dff44983b79f7a6, a19b2bd4ccdc9e687c84f4769e0c3cbc64a87fa3, 286217d1d3d0af78e5d61353ba8e8621a9636e36, be8e51d2177740741b54241defab4726e687b67c) -- Fix definition of `ConstDensityThermo::standardConcentration` (89fded32d46084bd7733c81c7d1b383922e433a1, #458, #490) -- Preserve constant property pair when multiplying `Quantity` objects (c9b0bce8b99000099763aedb088dddb80f7047a1) -- Fix `PureFluidPhase` state data consistency (fb68cae145d28556e4d7cc58ffc1ec871e0b0be4, 0417d31d0ecabd77d5b4fc24900ff0c2bc0620dd) - -### Kinetics -- Validate balance of surface sites for interface reactions (ac5337130a8d21728026f04155c0c85ad2ea0c5e, #412) -- Reactions which are declared as duplicate but do not have the corresponding duplicate reaction are errors (0fd2f7c4d0ba7de2c471ae57053421b8d8fbb029, 2678b57d587d39110325a07adcfa156424a0f326, #389) -- Fix use of `'scale'` and `'OneWayFlow'` options in `ReactonPathDiagram`s (0d982c8f582e08f0e77eff49f51f870b249d333f, 0249ce89b86b11d524525d2b265de857b3fe8ecf, #378, #424) -- Fix how species contributions to reaction paths are handled (3093e6e6d4d8960838492cb3848e0881420dc7b4, 5a0fb579a83c3081033421ef6363e6b31e901a0e, 092e00744bc6afc96bd14c130ea7162bfa9aa3d9, #377, #424) -- Preserve pressure units in `PLOG` reactions when converting from Chemkin to CTI format (7b7aea2038ecfad88af0919bf4104ac2a87b70e7, a02753ae792a71b4eda2028d4ea73d054ad5a4b4, #435) -- Fix style arguments for reaction path diagrams (b41038f84b705102900e56a7cdbdc141670be4af, #463) -- Fix duplicate reaction checking (513b43200c7b222d9ef992e00b922ef210961ad6, 4c489c175da4d2979a974b748a97a179f475508f, #468) -- Fix failures due to tolerances in some kinetics tests (67aa9eb4e3663f5507e0e6ec25b54bf74f4782c3) - -### Transport -- Fixes to enable `CK_mix` and `CK_multi` mode flags (35aa8be61e8e68907c4d4cff7c625907094c22c0, 435f28641ec81ae53aaa8851ee9fe351b5da08b3, 1b605133d8cb1c77b0348a9984c4b8fc64f55c2a) -- Add temperature dependence of rotational relaxation (e79cf6f8cb59c8f8c3d994c71316e12e966140a0, #547) - -### 0-D Reactors -- Fix using pure fluids in reactors (2ac8a0ef088166883ee1639ba12bd13462169e6e, deeaaed03f619e936b10e908bf9835e58dc10da7, #475, #487) -- Check that contents are Solution objects not Mixtures (a22db9fa22572df3be9446875607455cd3361d9e) - -### 1-D Flames -- Fix handling of domain boundary conditions when the energy equation is not solved (52dbe8c007921769287127701017599e37460598) -- Fix handling of Soret diffusion enabling/disabling with respect to mixture-averaged diffusion approximation (a03afbd56ee3b51f203a1ee9e7c2fa536c66b01d, 4bd5e92694f4ecf7dee5fdc5f48db21ea3d0b598, fde505113166473b1d5ad3cd61f6aed5dd7b9d4f, #511) - -### CTI/Input files -- Fix file size limit when converting CTI to CTML (0a1257daed71fdd621ac25bcdeea911d84036bfd, #416, #430) -- Fix for reactions with pathologically named third bodies (55a8910686d15071f300b2c2cec38812514f8ef6, 6d591b82efc9b8909ffaa6fe7e70812bdd8c9135, 44b24ca873b55085770563cd4f0b63a5c712412e, #460) -- `ctml_writer` is more tolerant of non-ASCII characters (0c0a38d4fe6465fde3f51f73ed6bf8fe47c9fd79) -- Fix incorrect entry in `nasathermo.dat` (3933a943dc6fa712fa8a5c920435b28d8e563353, #491) -- Fix writing surface reactions to the CTI file when there are no gas-phase reactions (552ba97a2b3e050c9564fdaaf830fe41f73430d8) -- Fix over-zealous detection of new input file sections (f47e98a594a5b43b8b41b38eaea49eca8f30406c) -- Detect badly-formatted values of the 4th Troe coefficient (bde6e0545293eb8a530174af6fbba34e4f2430de) -- Suppress some output when `quiet=True` (70016b97b3a9a1ec042f35394752891168321030) -- Fix duplicate key check in parseCompString (d09161716f2da9160dc7f08f017bfe57c546de84, #525) -- Fix spurious unexpected output warnings (fd57936b18a9bcebcffbe25316b23fe9123da18f) - -### Examples -- Fix errors and empty figures in IC engine example (6f564e6101541b5368b64b64e96eac4b64f366c7, 0d01d031a9551bf8252a7f7f2cb769c276ab3fe8) -- Remove extraneous arguments in Matlab example scripts (a31b7d1bb5be876729e4e7728a78f417cdf1b3dd) -- Remove or fix broken Matlab examples (536158b402893d14930d1da579c72d545dc72943, 987a247bd0d7b626e972c974faf78576a48b6552) - -### Other -- Add explicit dependencies on the `scons build` step for `scons test` and `scons install` (70e10632d4a451dec7e0f94ab2e09156b1a6848b, #432) -- Fix reproducibility of `add_species_sequential` test (11a0727d5ca6172fcb3596dbc11e7f7b1cc2e806, #433) -- Disable linking to external SUNDIALS libraries when building the Matlab toolbox (c125878a40f1395149c8e9a713aba90a0cb7cc44, #431, #456) -- Switch SourceForge links in the docs to point to GitHub (d920f2eb2cd7296086412746fd5e1e50ca2cd8a9, #442, #455) -- Fix typos in documentation (05809bb027a7232badae3dc3eb970695437e19b6, fec6c34ed8052f0ee4b86e6a3c37769eba917ccc, 35ac1acfa87c4262931ec7acdd62de2629353550, af4ccaee099486d60c8eadab3fe823cd427b131b, #449) -- Easier debugging of NumPy import error messages during build (3f69f6ac8a45196e0f0b9244e01fed06c6b0c64e) -- Use Trusty Tahr and system Python 3 on TravisCI Linux builds (9e5da87a2a07455b0c1b063c9494123561ad5c87, 45891a2118dcd8146a1485741e9b156df271f048) -- Fix parallel builds of the Matlab toolbox (831239633daa7a86f7774c62260c27a0354ab456, #483) -- Remove outdated MacPorts installation instructions (46f8ef52a7c6041e1cb29e68d58cd7dc97ba1d2d, #496) -- Fix wrong environment variable MATLAB_PATH -> MATLABPATH (d86a7c176e7bf35617728a1b2771ae673f67f351, #501) -- Fix broken links in README, clarify PR template, add Gitter, add badges (e052a44e92b1492d5515f1b759f8f2fb7d6ffa13, 8de267f25c9cbb58527445838ebcdc72932156bb, de3ec3d53e3645f24ae0353d3edc83a122e4ccb4, 0120f2fc5e2d431171476703cb2957960445f873, #505, #506, #513) -- Fix installing dependencies on Appveyor (39c4103504635cb620ba6e4997ce657a4ea546e9, 0b8f0283aacbb12b7f9ab4f9f016be781bd087a6, b1a010e3a3f464ed0a58c33f8265c43fc73ad8b8, #517, #529) -- Add update of git submodules to code checkout instructions (66ba4b5b507fd182a35f0b3310d22fe9ee72e51c) -- Remove blank documentation page (84acdb1a300d5d5d943f579b2d03f3f5067b2514, #518) -- Fix notation for mixture-averaged diffusion coefficient (df6ecb101b4617348419eb46786215863bf65bcd) -- Fix compilier warning about `m_Faraday_dim` (55490de87103563fc40e0645613ac3e69cdd15a6) -- Fix catching exceptions when checking git commit during build (3fac5f2bc6f9060b1e24ddec12632e905b113f75, c8305375efa93df460a9348ca7f6aaecdcadb94f) -- Fix display of information from errors in Python callbacks (d3f49e74cb5a24722aff23db5c8e0dc14becbc07) -- Clean the correct folder after building the minimal Python interface (ff91457b5af7ffe2962a15b5609ca95dbf656e30) -- Fix building MSI for Python 3.7 module (af51a61ab1be3aca6ac7f7bd7094357ba4ab58db) - -## Changes to existing capabilities - -### Thermo/Species/Elements -- PDSS objects store their own data (50ed3f2e7265baf3ae65629ba67edfa68e199f11) -- Remove `VPSSMgr` and merge into `VPStandardStateTP` (b39537bfcbdc8f89e607fda8822c3061aa580b7b, #428) -- Simplify aqueous phase creation in `VPStandardStateTP` (3ea2a6caf32d31bb06e12ccc4e137a762ec9eec2) -- Allow instantiation of ThermoPhase derived classes without XML (86dca05369189b9b0c32cbe960ac416f0eee7ab1, 507a3a9985f2b0237f8d13442d6ac93f37a781d1, 19c17d149ba92f9f68415354cb6ac32b7e2c893b, db1f1af0a0c376747591ccdb0c77cd6487727c65, 5efea129599cfdb7a4d7f580c145db95dde15b9c, 3c771ded2bf184b4cffb362127fd77ba35390da4, b033d44d3e00a1c4a36cd1a501ff77d34da18bbe, 31d54c3b111b2d01468faa61060d8330969dd043, 95a52b2d34d7bd65e58145e30436c4e88b8b777f, f8ef4a8b2b3efc7392b5cdfd2a378adddf7579b8, a6ac446021b8a8b3b314f4d8f8dc8bb81ee66ac2, bfdc2b9e1d26d1ce9fad758a453a3f8e5f39829c, f69ef446007ee73ad8c5f527605196b514feca6e, d744bd9fb8c0cdbfe48b77ef4ae4d39d3cd71647, 3676672eec57e5e66a9ef7b50a3449bcdd184a3e, aa02d2423583968132a29a980df6cb3a2d818491, e3afaf5e6151d85e1c8ff56a3a752fbc3b170955, 3790115b99ff927212c0e498fd18931cd550c5e9, 4c630fc59211b5ebe878afef99baca7637c81a3f, a520f782dbe10ec42db449c5a90ed44b917f004b) -- Clean up and test `RedlichKwongMFTP` implementation and remove broken "sanity checks" (ecbd819e91340ac563ec837bc3347034e69a196f, dd521de25439115e4653389221e844e56c231db3, f9d5f16b729bed36009d7ef9ddb4a042f798cfe0, #267, #436, #438) -- Move common PDSS functions into the the `PDSS_Nondimensional` class (574462fd3c6d6db6c2d785cc2de0ea745010199c) -- Remove unused thermodynamics models from `ThermoFactory` (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. (2b73fe24baa6a10c36dcbc05e4fea2958346da78, 6d22be2a6b282808ad5effa5fd5bd7dca08b0b84, #267) -- Remove unimplemented options from `DebyeHuckel` (afafa34c06640037af82ea1682d6d8c74ae84b36) -- Charge transfer reactions can be set for `surface_reaction`s, not just `edge_reaction`s (51f419fbadef27d318f249c447400a1618a6d151, #439) -- Remove unused members from some thermo classes (4818c87344d8d5076ec9dd2808061cdd4a1b38b9, 6bfd82e0be67a41986c07877ec973a9a97fc0d29, 90d18dd3375c8c87dacecea34e253d5a01d8d8a5, c85ba586d236a27b6aefb8864e3312e5299b0c3a, cfc3b728f5a7f833c80948d4b6332648882604d6, 6ca782030dae74333263d4456e2da7803decdbf7, d07908f9c99e560992098d8ebdb367c6c93dd2a4, 4b69c7f2654d939204a8b58d8084c70ce3599814, 572af616e7ed767d306fe439c0d7dfaad9e1225b) -- Store several class properties as `shared_ptr`s (04f10972c8daeda802d600f5104dba59cc7d2b3d, 4856d1328b9339459725d63a1e76671e15d91052) -- Remove debug exception from Phase::entropyElement298 (d4338249fb29d5de9a1154980dcb01d603354cc0, #467) -- Explicitly assume that the solvent species is always the first species in the phase (e33fe6904d573ddd141ce5a619a24fb873137746) -- Move implementation of `HMWSoln` to a single file (e9f08fc58e53b6061df0e75991e2c9d378eafdfd) -- Try to look up standard entropy when adding undefined elements (0ca788bd69cbc7b8a3e4ae319d6668ce6a96b1a8) -- Always use `PDSS_ConstVol` for constant volume standard state and remove the implementation from `PDSS_SSVol` (822cdc7d38b3fd609269f5d7ee8b3ff9e4e1b6cf) -- Make adding undefined elements the default behavior (d03555753130b9e4a9bfec10d17579fcb2038290) -- `set_equivalence_ratio` now supports sulfur oxidation (48eaedbbb44b25bab9c2938d04e508eaa9e564ec, acbd65d1922a601ced413a7d43a20540cf8b2944, aac8eb92afd4191b3581258e0c6ea17348471858, #474) -- Relax warning threshold for heat capacity discontinuities (a68c048bfa4e32392bd2faaa6740eaa76d98cacd) - -### Equilibrium Solvers -- Various clean ups, refactoring, and simplifications to the VCS solver (ee323bbafc12926aa0c532047a1de4b550c6d067, 08726b0904bc40ae182f7706b0172f04d8f4cb2f, da801f4cbcd7c5c070e926a5fb54fbcb81c1c7a2, 8522095deaacc3659b3195c5a5638bbe5b6aa606, bba0d8edf0a96a07ca26c07351eba51216b3682b, 1eebd3efdbd469556b8a4c3800fc0499424d6513, da3ba35945210644b10aa2900b846a05dd54f80e, 4e53c893cfdfa84ddd20868962b1c4e733135891, 7eb939dc5fb79c548f813c7160836d07f24abc26, 739d4e483011c940840134a0e84ae2796a5cf473) -- Improve control of logging in the ChemEquil solver (5b4a977df7fb3fc7b80363ed84a4a035018e5e27) -- Don't use saved element potentials as an initial guess and deprecate getter/setter methods (74167cc3eb81dc63b306c045e2a7b1e86fb5b08b, 3c978cdff6bb950c609b15215eb3d8f608abba96, #538) - -### Transport -- Allow construction of Transport derived classes without XML (4b5af640505c686790ba5cf749274fbbaa61cb12, 7020fa72bfd7821b46a1b6ae29567e362f940e4f) -- Move `simpleTransport` test to GTest suite (4934079d69fcbafadf3ac361a9ddf2926c9e051b) - -### 0-D Reactors -- Make all reactor-related objects non-copyable (d9418bb8fbed2b591ca025a32a8c5c1d5591333b) - -### 1-D Flames -- Make all 1-D-related objects non-copyable (279c5c8556340e8112c78aa9b7d3d39b9e90236b) -- Deprecate `FreeFlow` and `AxiStagnFlow` classes by moving the relevant functions into the `StFlow` class (c1067aa6e97584d09da63cf6abdddd110522a91e, 3ade3335de105506d83f8550a1ca9525bdcbce01, a54ab2f3efec19715039cd7c064902c5050eb2c1, #546, #548) - -### CTI/XML/Input Files -- Make searches for child nodes case insensitive (1bd950fef558101d7e8080629b7e6c1d86fd0fe9) -- Improve error messages for invalid (floating point) geometry flags (6bf74d179b04848b756791de59f830bc46fb7537, #446, #454) - -### Examples/Samples -- Remove verbose output from f77 demo wrapper (172e9ffeadd8653ec309321dda61e68e0c508008) - -### Documentation -- Note requirement to use `modifySpecies` and `modifyReaction` (4b4128aebd02140ac26fc84627d618b70c5e82dc, #394, #542) -- Clarify the values returned by `getFwdRateConstants` (831b92dac4fd5b39ab9762a09ea5b3050927c173) -- Move most content from the old documentation to the new website (7b6d04c381e9ae1bcec61c53c761412ef81422ef, cc9c8e5633da0c69077064e1092d0a87f387fb25, 71072c43db9eecba08a017b6fb44d811fc25f6d2, e81cac9582d1492eff7c1c0feeada9a5501e91c1, e7f346cddf7713837fb907cf6f898605acb3d2d0, 7a69386b8db61e2a9fed74855def5f156e8795ca, d57f1d147dfe8ced738ad0f489cd4917b5d2d9a4, b68a87d62466dc0e55c9c8512573da0ae7c4c25e, 21db5d84f3ce60a3be79392531df3a19f2d87fa3, 3052701250034ffad1bf575b790ea1e4659314f8, 2a7aed89687db2048bd262d0acea27de62883c5f, e8d28b0e89fae05e5b7e1d01f88c67a8934380f8, dbc3df168701f631b6554ecfd74565b1c9c8f1a0, 2f3a0122d65ff66552dc8ed4870d0b3edfb9d764, 9670c5dac6aeae078fcb4414da4fbebb33ab116d, 3fae1c1a9aaa6c26945d71bcb81be7a9af808697, 4ea9d35a2b3dc8b94d1d9681ce109b5959cdd811, 549463683da253f16620493ef50788d09a61476c, d2252037c66ce3451c5a12ce5adac3c9f518294f, c28bc0235f1b8772ce6176adb76b7c96350d248e, d33e67c36c46846f8d30fb989a1a9640c67883e5, 7e1b6a1489d4545b0dbe3d9fe92a0aa9943e8247, 33840414e5a3d21a5f9cb25278fe9e2685c590a9, 0d559778a7a17f5e54ba99419961fee76e39ac64, b84d3e3f79c63b9d496fcc4d413f49cec1c04111, 053267e254dda6e7367969c4a59e936b50e2a802, 1864e8fd6c845cc61ab62f403a7f574ffde9107f, 5f556acd34597a352665359188dd80aa87ded536, 045f3d37bf330dca5d2492a3a03d1eeecb7077f3, 1ca6c5eb402db482db0958232ab2e1231f8e8cf9, 323c7370db1e20e507d9f95038ae6186eb51fe3e, #544) - -### Other -- Move MixMaster into a separate repository (886d7b7cdc8326fa39cd180cbc0429cae0c8f873) -- Propagation of environment variables in SCons is more sensible (e5edc319de58ce7506586ec02fcd1826b900ed71, 3c82c3a6c63920f9d60604d64d07a7f5d67340a6, eae9250f2efcb365a1a99b11d74accaf04e19bd3, 66998a5ae17222e65a6818047617413317754c13) -- Remove deprecated code (7673f7cb529070c24d54231a2c6feb0d7514bd8d, 3accd415e81012bc1b88832e7f29f86fd4922598) -- Print error messages from and pass flags to GTest (fca22d94e5ecb1e8b359e4a1ce8cd4f840c803b5, 461b63e462be2edc1a99dd96aee104bc60d44794) -- Remove the requirement for clients to have Boost headers installed when building against the Cantera library (713b9cc23cd4fba835fb8b90e2762c3d48e3685c, f8d183220c42e084bd2b5a26fb7c613aadaed462, 686250e51f25bd0807af80dff37e5aa89b2f7df9, 87a7deb35d829393e9d7ff108d71cc95248694ea, 83ffd844d1a23a7dec695726468fd081629fe81a, #480) -- Update to GTest 1.8.0 (60d20754923ee05cea333f70a0d81486abb09a92, #482) -- Remove `HAS_NO_PYTHON` configuration variable (16fd18315c461a854d5d718a31608b1776aa20d4, #483) -- Change the options to build the Python interface, since SCons can be run by Python 3 (94ea9b585f087d7a325df6e0a908869d3b1cacfd, 2bc4d09da380903e68c23946e93ded10e65ebbd5, 6ca67b48452bb87b12bdb5f9caaef5b3b60cca98, 11943bbc6f7f6c81c682a49f180d6b89ba1839e8, 7054a7bb3d994303151269ef9688f38deb184ac1, f824b20fe28ccdc7a0e84b3b72b37dd7d8fb695d, 43b42e99420083c04762a08daf96e27a8385f714, c233ddcd30eb296b59d5dcab59409d9ebd1311a3, 9f4590bc6f16f69c34f17487362aa1163891593d, 9c9ee9e9191df2b9b5ca6a4e3ce2a37efa733023, 5d599bb680e03f3918244a0a13e1ae4015413d0d, 4e6af27edf6cc3ebbf90311be827fdc95e5697a1, 3e39a0bc3d0141b3205466396f37cbd6dcd30b67, #483, #486, #488) -- Check for 3to2 during build by importing the library, rather than running a script (77ee76c5f30b73f17c873874842336a86f1da396, #483) -- Use std::sort to eliminate need for vcs_optMax (07eed363fe9f2d6287db674a44ef4353980b7256) -- Google Test suite can be disabled entirely (fb4a36b1ca84032704d55fa2baff8f48c980d1ac, 9bad3545534b022dae579a1df138f005be7695da, 333d388f90a8d318f3dadd0e70bdcf955e1ec7bb, #535) -- Improve behavior of Matlab test suite (bdaabc0428dbb28e4a0d6bd037ff2d4971238d33, 677efd82d57543577ba2455c59f2ab4e35cdad00, b5b542d10b837220aaa59a0013b7d3aed922d1dd) - -## Additions - -### Thermo/Species/Elements -- Allow synonyms for Factory model names (c28ca48cf8cbc9075ad3817b700640faad1e848c) -- Add electron to the built-in elements (974bbc7da44998f4ec8f107363bbb53661fb4b0f, #443) -- Identify unspecified electrochemical reactions (04be9888ed56d14c61ce7c2b9abd58e55e9ce47a, #452) -- Make activity coefficients and activities available (a5b0bdf69547b638b7e03c5aa0273a34068eebe9) -- Add regression tests for some thermo classes (338b21694f4840a0a54a7ed3cb8b5555aab87462) -- Create a default constructor for PDSS objects and avoid unnecessary arguments in the initializers (04cac2b2771c605cf668195f04551b209838ace5) -- Show values in `setDensity`/`setTemperature` exceptions (ebc478f8ec46eae1cda179e6b65536af268bfad7) -- Add Cython function to access species viscosity (cc93ce62ca23ac9dca8074d10d3c0531387ba864, #527) -- Add `get_equivalence_ratio` function (a9ad75e974b7d1aed642a23f5b58ff7bd27a2d8d, #521) -- Add `newSubstance` method to create pure fluid objects by name (62c67e4ad1f57763c25393382e7901c8fb131713) -- Allow `surface_reaction`s (not just `edge_reaction`s) to be charge transfer reactions (51f419fbadef27d318f249c447400a1618a6d151, #439) - -### Transport -- Add unity Lewis number transport model (d38d9da32c0ecbebde25b4a33f56635f20316e0b, 29a3c1939960beae7a651f6fad0b754856fd5de7, 3c3ef10f9321f418db3caf9394ee551635588da3, d4492f3ea39bb991f493407470b31b22e7ba8e42, a1c12b4a3b69c91e17bb2a156116c779e477c85c, #510) -- Add ion gas transport model (b7e32e4604a9de401ea651f5a3142fcc04de1711, 3a0f46eb56f8a99a7152db36aa1b991538048bb9, eeb27d84a9c1a374da9bf7b4409370c62580aa84, f7852ad84c078cbbc39cfc1e23ff72087a57efb5, fa9b9374cfe8c11349866a475c4ebf535f47368a, 1245a694e522dbd9df0fdceb004b42816e0554f3, 5c783c708f0c08def6f6a3d8328b336d65842357, #539) - -### 1-D Flames -- Add access to current solution resdiuals (6a52908d8571b171bc5685944f185f0aefef4bc3) -- Allow user to pass the locations where temperature is set during flame initialization (2a38b0a765aee9fe0baae7d42fa8763591f09352, #447) -- Add ability to simulate ionized flames using the `IonFlow` class and the `BurnerIonFlame` and `(3b12c6d6623c83a1013398aa694b9dd4d745058c, e2f718c65b75e3d3670e9b774a79d2f4f1c8606e, 9dd0134e3135720c43b01c7bf9b6961cddc4359e, 6b6d758f2390487b7952916c4f3a9fdec535a59b, 1057d2073182628e790c70df0a42f812687ff340, 1be837434240a8610f164ee14355d4f0eee27057, a8cbfd2c41fc324ce40b59e6e2ac8c192e97fd83, 2472e080c377fad61162d04200f385cc3096a39b, a99004d8ef2cd802ce8923f08bf8cf9486c7e9cb, 24940aeef774e91156cbaa15e8e219b4c35287ad, c3ba26428421f2edde473d11ad4831da2c9afe6b, a5762ea6b6ee40cc74b32ce0871ae1f788417a87, ac8612f36b7e317fb01e25a33d1edf4ecbfdc604, #441, #471, #546, #548) -- Add function to get the refine criteria used in a flame (bce4210e1b2bf424c2d1e7f1ded45cfcdbfa761d, 4b44c6618285679d00969cddcd12310586240c48, c88ddce0d69523b9dab1cc09a1196726de0d6dd9, #469) -- Add a more general `CounterFlowDiffusionFlame` to Matlab, replacing `npflame_init` (43bd96b5ba6073bd952dd2231daac3ead40e1ff7, c092484f4df60caf0c967df4552eedf2c010eb53, #450) -- Allow access to and disabling of callbacks for 1-D problems (4b352751f54a033f731d3d69c43c9afe6da559d0, 7a314d3124bb74583850e9ede8d265f1605ae7bf, #489) -- Automatically detect when the domain width is too narrow or the flame has blown off the burner (dfd4b7e671c847cbe2aa6b1e1ed49b0215727990, 7eb4eaa13aeb77a4d723d80739e4496e75276807, 4911539b565bffd0b30ffd26e04c30f085b85768, #489) -- Add `BurnerIonFlame` class (2527869536bec16a9e92a593d9389b632dac1409, 5082a212c446743e57996d403c1061037864d540, ee633f3e16314210ecdd7edbfae8b519f274aac1, 166249869b5c3c828bfc63563de4a2c826047be8, #548) - -### CTI/Input files -- Allow negative reaction orders (8f02c777a5904069e8c8b57ae695be1fb383f033, 4771874c757942807f40baa66e8a90e8f69ef25e, 501b5fd1f52360464e55a047b92473ca0a89686d, #485) -- Add support for parsing species with specific site occupancies (89bca5fcd1d8cd964abc731d8852d5ac87914e3c, #444) -- Improve error message reporting during failed ck2cti conversions (4b5a37a3362b7c6001f021256c3241e3e592284e, 9c3b500ec869080c166485f37e2ba39c987b6f7e, 4affcd1efb4f99843878147e678b7e6a9e62ccb1, 411be3e6cf1d110143fdf893c8a050762f7dc6c7, #497) -- Allow `convertMech` function to be called multiple times (277aa0b91328748d266db644b12edd3934cf2ac7, #528, #536) - -### Other -- Add methods for getting the git commit (8e89bbb8d2dde80b59b2533563ff67c935addd41, 7979a2b52a791d0e22e161a6400590514ed024fe) -- Add class `AnyMap` (56022e898915c32ecb768fd8a48ec6054354a94c, 9c084d5c84d010ca98d870c73139783cb769a87c, 7fab7f3cd3deec74e649a522b37e10efdf238e79, #443) -- Add compatiblity with Cython >=0.26 (8d953a9424700b85beff13a83fe7a6921768dd75, #465, #467) -- Add compatibility with fmt 4.0.0 (ea69a014a54ac0fb5199c63b4b673af0b3eff23d, #470) -- Building now supports SCons 3.0.0 and Python 3 runnning SCons (7d0bc71448f549f3486c5c552c569f1e1f0f5565, 684262e945f67498fb7ab460578249ed7bd11188, #477, #478, #481) -- Allow building and testing with msvc-12.0 (e921cb89c8cb3c167919344277009d54ae711255, 6844e527137bf265ca8799f408aec1053b66b48a, #479) -- Add `setup_cantera.csh` for use with csh/tcsh (4a4886f63ef21e763092ec04876215b61962dcab, #453) -- Add conda GCC compilers to the check for C compilers during building (07409dea59cffa57e4dba91087e52d1201b4eb6e, #486) -- Many documentation updates related to Cantera joining NumFOCUS (e846505f5783a979b245974a61a0d94e241ccbd1, e6b4761c6bbc31484afda0af29e6f8450e41fb21, af4a78dddef088785916cf1058c28444e33b463d, ec5aecd3d6cd422a78df5225aead2952d04a04ee, 419a09c4145f2a5803f1e30a4554478ffb30235f, 581cfb7c042289d4dc7eda32bdec9017d5346137, 8caf5e5aca2549d7ba2075b6312de64004d346a8, 977a1c7736aaf177138ae297fce3ef8b77494954, 0d20b50543815370244b112f9e0247568158ae19, c78a11b32f6d1613dce77cf2120ecaab96880b08, 2abc57e2f1324d5e30537f01d39c15b88fe4206f, 05fa4df3b9ebe4a8ea644dc23101d7cc62414404, 8195403fefc63fd1f36707ab36b7495d5fdc22e7, 1a394a3402d929a4acbd47be8a4e22240ece35ed, c29fbc808e1a1073ff823da1076d066607362662, 66597b72ffcdabd199aebe53b7654962188abe29, a0ac2b0cc62604009f529037001fb544176b4db3, #502) -- Add support for SUNDIALS 3.0.0 and 3.1.0 (50a3fecb23f4cf97e71d989812a48c1a4c40f754, 9c50f7528c71ef470d73939f580d03ea342d85dd, 82c959d3a39fbe0e4ecdb0ceca9dff81c9e0254b, 322b1fc37572dca61067397d460cc809b9bece46, #503) -- Upgrade Eigen submodule to 3.3.4 (20f891f1a43acb5fd72963bf34ba101e10fcbf4c) -- Add links to old versions of the documentation (b26dc65c415c69af050f1ef28c5505f10f5800bb) -- Upgrade `fmtlib` submodule to 5.0.0 (6b3c912ec3147c1cb91e57a21bda30379746c88e, 99d4972e6b962ed91ef7dc8fb6943416fe86c846, 3be3f7dad5291aa53c633e3043768d7527e54148, e42b952a8ac88b46d274cfa034e5f3617e1d8c0c, 51d0d43a4505cb680e073a552cbb31b0f385460d, 309871ae8823aa182e4f7a6fb2d8bf3a456019a3, dab739013ed2c766583cf27cc0617ff68f77c64d, #540) - -### Examples/Samples -- Add C++ OpenMP example (78d5809d6f3e79a6afb6dad211a0417c56bd5065) -- Add NonIdealShockTube example (2a601c148f9f586d72e247162946e64739477e4a, e78aac7b70265705aef4d62cde8c675003dc50e5, 26216e9adc9eddbd7466b0ff068860148134241a, #473, #483) -- Add example of PSR/WSR that replaces `combustor.py` (dc5ec06a0c020715ccda93942e50c2d2281ee51b, #550) -- Add example of using a time-dependent mass flow into a reactor (2f67c9969d6ff2020410fa7ea5abc782c528dc6f, #550) diff --git a/pages/documentation/release_notes/v2.5.1.md b/pages/documentation/release_notes/v2.5.1.md deleted file mode 100644 index f565ee2be..000000000 --- a/pages/documentation/release_notes/v2.5.1.md +++ /dev/null @@ -1,134 +0,0 @@ -<!-- -.. title: Cantera 2.5.1 -.. slug: v2.5.1 -.. date: 2021-02-13T00:45:18Z -.. tags: -.. category: -.. link: -.. description: -.. type: text ---> - -# Cantera 2.5.1 - -Published on February 12, 2021 | [Full release on Github](https://github.com/Cantera/cantera/releases/tag/v2.5.1) - -The Cantera development team is pleased to announce the availability of Cantera 2.5.1. There have been 1000 commits to Cantera since the release of Cantera 2.4.0 in August 2018. We have closed or merged more than [250 pull requests](https://github.com/Cantera/cantera/pulls?q=is%3Apr+is%3Aclosed+updated%3A%3E%3D2018-08-24) and [100 issues](https://github.com/Cantera/cantera/issues?q=is%3Aissue+is%3Aclosed+updated%3A%3E%3D2018-08-24). The complete list of changes can be found on the [Cantera Wiki page](https://github.com/Cantera/cantera/wiki/Complete-git-log-between-v2.4.0-and-v2.5.1), and a summary of new features, changes, and bugs fixed in this release is included below, with links to the associated Pull Requests on GitHub. - - -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. - -Thank you to the following contributors to Cantera 2.5: - -[@12Chao](https://github.com/12Chao), [@agarwalrounak](https://github.com/agarwalrounak), [@arghdos](https://github.com/arghdos), [@band-a-prend](https://github.com/band-a-prend), [@BangShiuh](https://github.com/BangShiuh), [@bryanwweber](https://github.com/bryanwweber), [@CyberDrudge](https://github.com/CyberDrudge), [@decaluwe](https://github.com/decaluwe), [@dholland88](https://github.com/dholland88), [@g3bk47](https://github.com/g3bk47), [@inducer](https://github.com/inducer), [@ischoegl](https://github.com/ischoegl), [@jsantner](https://github.com/jsantner), [@korffdm](https://github.com/korffdm), [@kyleniemeyer](https://github.com/kyleniemeyer), [@lavdwall](https://github.com/lavdwall), [@lionkey](https://github.com/lionkey), [@manikmayur](https://github.com/manikmayur), [@mgashwinkumar](https://github.com/mgashwinkumar), [@paulblum](https://github.com/paulblum), [@rwest](https://github.com/rwest), [@sameshl](https://github.com/sameshl), [@sin-ha](https://github.com/sin-ha), [@speth](https://github.com/speth), [@spinnau](https://github.com/spinnau), [@ThanasisMattas](https://github.com/ThanasisMattas), [@tsikes](https://github.com/tsikes), [@wbessler](https://github.com/wbessler) - - -<h2>New Features:</h2> -<ul> -<li>Added a new, YAML-based input file format (<a href="https://github.com/Cantera/cantera/pull/584">#584</a>, <a href="https://github.com/Cantera/cantera/pull/663">#663</a>, <a href="https://github.com/Cantera/cantera/pull/664">#664</a>, <a href="https://github.com/Cantera/cantera/pull/671">#671</a>, <a href="https://github.com/Cantera/cantera/pull/693">#693</a>, <a href="https://github.com/Cantera/cantera/pull/707">#707</a>, <a href="https://github.com/Cantera/cantera/pull/708">#708</a>, <a href="https://github.com/Cantera/cantera/pull/716">#716</a>, <a href="https://github.com/Cantera/cantera/pull/723">#723</a>, <a href="https://github.com/Cantera/cantera/pull/738">#738</a>, <a href="https://github.com/Cantera/cantera/pull/750">#750</a>, <a href="https://github.com/Cantera/cantera/pull/764">#764</a>, <a href="https://github.com/Cantera/cantera/pull/768">#768</a>, <a href="https://github.com/Cantera/cantera/pull/773">#773</a>, <a href="https://github.com/Cantera/cantera/pull/784">#784</a>, <a href="https://github.com/Cantera/cantera/pull/794">#794</a>, <a href="https://github.com/Cantera/cantera/pull/795">#795</a>, <a href="https://github.com/Cantera/cantera/pull/813">#813</a>, <a href="https://github.com/Cantera/cantera/pull/855">#855</a>, <a href="https://github.com/Cantera/cantera/pull/857">#857</a>, <a href="https://github.com/Cantera/cantera/pull/866">#866</a>, <a href="https://github.com/Cantera/cantera/pull/869">#869, <a href="https://github.com/Cantera/cantera/pull/880">#880</a>, <a href="https://github.com/Cantera/cantera/pull/897">#897</a>, <a href="https://github.com/Cantera/cantera/pull/899">#899</a>, <a href="https://github.com/Cantera/cantera/pull/961">#961</a>, <a href="https://github.com/Cantera/cantera/pull/970">#970</a>, <a href="https://github.com/Cantera/cantera/pull/941">#941</a>, <a href="https://github.com/Cantera/cantera/pull/974">#974</a>)</li> -<li>Add interface for reading and writing 1D Flame and SolutionArray objects from/to HDF5 files (<a href="https://github.com/Cantera/cantera/pull/680">#680</a>, <a href="https://github.com/Cantera/cantera/pull/687">#687</a>, <a href="https://github.com/Cantera/cantera/pull/805">#805</a>, <a href="https://github.com/Cantera/cantera/pull/840">#840</a>, <a href="https://github.com/Cantera/cantera/pull/860">#860</a>, <a href="https://github.com/Cantera/cantera/pull/871">#871</a>, <a href="https://github.com/Cantera/cantera/pull/900">#900</a>, <a href="https://github.com/Cantera/cantera/pull/943">#943</a>, <a href="https://github.com/Cantera/cantera/pull/931">#931</a>)</li> -<li>Add BinarySolutionTabulatedThermo class, which implements implements tabulated standard state thermodynamics in a binary solution. (<a href="https://github.com/Cantera/cantera/pull/563">#563</a>, <a href="https://github.com/Cantera/cantera/pull/606">#606</a>, <a href="https://github.com/Cantera/cantera/pull/637">#637</a>, <a href="https://github.com/Cantera/cantera/pull/640">#640</a>, <a href="https://github.com/Cantera/cantera/pull/725">#725</a>)</li> -<li>Introduce C++ Solution class to simplify creation of coupled ThermoPhase, Kinetics, and Transport objects (<a href="https://github.com/Cantera/cantera/pull/696">#696</a>, <a href="https://github.com/Cantera/cantera/pull/735">#735</a>)</li> -<li>Determine Redlich-Kwong parameters from a database of critical property data (<a href="https://github.com/Cantera/cantera/pull/574">#574</a>, <a href="https://github.com/Cantera/cantera/pull/576">#576</a>, <a href="https://github.com/cantera/cantera/commit/33e198f7e527dee6a97869d6677d2da9b58247b1"><code>33e198f7e527dee6a97869d6677d2da9b58247b1</code></a>, <a href="https://github.com/cantera/cantera/commit/ebb93cb5a23591ca3badb186940e5b1a89e8a411"><code>ebb93cb5a23591ca3badb186940e5b1a89e8a411</code></a>)</li> -<li>Make transport property calculations available for pure fluid water phases (<a href="https://github.com/Cantera/cantera/pull/558">#558</a>)</li> -<li>Make InterfaceKinetics.advance_coverages_to_steady_state available in the Python interface (<a href="https://github.com/Cantera/cantera/pull/592">#592</a>, <a href="https://github.com/Cantera/cantera/pull/610">#610</a>)</li> -<li>Add functions for returning the phase of matter for ThermoPhase objects (<a href="https://github.com/Cantera/cantera/pull/722">#722</a>, <a href="https://github.com/Cantera/cantera/pull/839">#839</a>)</li> -<li>Add new ReactorNet::advanceTowards method to combine benefits of both the 'step' and 'advance' methods; see 'reactor3.py' example (<a href="https://github.com/Cantera/cantera/pull/629">#629</a>, <a href="https://github.com/Cantera/cantera/pull/756">#756</a>)</li> -<li>Enable setting the maximum number of CVODEs steps in the Python interface (<a href="https://github.com/Cantera/cantera/pull/581">#581</a>)</li> -<li>Add factories for FlowDevice and Wall objects, to enable creation of user-defined derived classes (<a href="https://github.com/Cantera/cantera/pull/632">#632</a>)</li> -<li>Allow classes derived from StFlow to have additional state variables (<a href="https://github.com/Cantera/cantera/pull/624">#624</a>)</li> -<li>Add wrappers to make "piecewise-Gibbs" and "NASA9" species thermo objects accessible in Python (<a href="https://github.com/Cantera/cantera/pull/711">#711</a>)</li> -<li>Add set_equivalence_ratio function to SolutionArray objects (<a href="https://github.com/Cantera/cantera/pull/677">#677</a>)</li> -<li>Add ability to sort SolutionArray objects (<a href="https://github.com/Cantera/cantera/pull/688">#688</a>)</li> -<li>Support use of Sundials versions up to 5.7 (<a href="https://github.com/cantera/cantera/commit/5e226535de33a73dd59429eb54ef5d157d0afaa1"><code>5e226535de33a73dd59429eb54ef5d157d0afaa1</code></a>, <a href="https://github.com/Cantera/cantera/pull/672">#672</a>, <a href="https://github.com/Cantera/cantera/pull/780">#780</a>, <a href="https://github.com/Cantera/cantera/pull/814">#814</a>, <a href="https://github.com/Cantera/cantera/pull/974">#974</a>)</li> -<li>Add functions for setting species aliases and finding isomers (<a href="https://github.com/Cantera/cantera/pull/714">#714</a>, <a href="https://github.com/Cantera/cantera/pull/876">#876</a>)</li> -<li>Added 'warn_user' function as a consistent way of issuing warnings from C++ (<a href="https://github.com/Cantera/cantera/pull/741">#741</a>)</li> -<li>Add get/set equivalenceRatio/mixtureFraction functions to C++ (<a href="https://github.com/Cantera/cantera/pull/851">#851</a>)</li> -<li>Make getDeltaEnthalpies available in the Matlab interface (<a href="https://github.com/Cantera/cantera/pull/659">#659</a>)</li> -<li>Add 'TabulatedFunction' class for providing time-varying reactor inputs specified by tabular input (<a href="https://github.com/Cantera/cantera/pull/797">#797</a>)</li> -<li>Add plug flow reactor example in MATLAB (<a href="https://github.com/Cantera/cantera/pull/701">#701</a>)</li> -<li>Make liquid-water-IAPWS95 available as a phase model (<a href="https://github.com/Cantera/cantera/pull/921">#921</a>)</li> -<li>Make species charge information available in Python (<a href="https://github.com/Cantera/cantera/pull/863">#863</a>)</li> -<li>Add 'kinetics_species_name' and 'kinetics_species_names' functions to Python interface (<a href="https://github.com/cantera/cantera/commit/5601ee906741a539b8316ad9dad0cc7dbf4d6d68"><code>5601ee906741a539b8316ad9dad0cc7dbf4d6d68</code></a>)</li> -<li>Added 'list_data_files' function to Python module (<a href="https://github.com/Cantera/cantera/pull/589">#589</a>)</li> -<li>Add 'fast_fail_tests' option to SCons (<a href="https://github.com/Cantera/cantera/pull/772">#772</a>)</li> -<li>Add some functions which were missing from the Fortran interface (<a href="https://github.com/Cantera/cantera/pull/828">#828</a>, <a href="https://github.com/Cantera/cantera/pull/858">#858</a>, <a href="https://github.com/Cantera/cantera/pull/870">#870</a>)</li> -<li>Provide const versions of certain functions (<a href="https://github.com/Cantera/cantera/pull/850">#850</a>, <a href="https://github.com/cantera/cantera/commit/9aa507a0988e9b12724f1c25ef23a67f4b04cd27"><code>9aa507a0988e9b12724f1c25ef23a67f4b04cd27</code></a>)</li> -<li>Expand '~' as user homedir shortcut when adding data directories (<a href="https://github.com/cantera/cantera/commit/ca8700fdd406f148dd27bb238fc748f00ede69f4"><code>ca8700fdd406f148dd27bb238fc748f00ede69f4</code></a>)</li> -</ul> - -<h2>Changes to existing features:</h2> -<ul> -<li>Remove support for Python 2 (<a href="https://github.com/Cantera/cantera/pull/560">#560</a>, <a href="https://github.com/Cantera/cantera/pull/611">#611</a>)</li> -<li>Update physical constants based on 2018 CODATA values, and atomic weights to 2018 IUPAC/CIAAW values (<a href="https://github.com/Cantera/cantera/pull/653">#653</a>)</li> -<li>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>. (<a href="https://github.com/Cantera/cantera/pull/580">#580</a>, <a href="https://github.com/Cantera/cantera/pull/588">#588</a>, <a href="https://github.com/Cantera/cantera/pull/645">#645</a>, <a href="https://github.com/Cantera/cantera/pull/643">#643</a>, <a href="https://github.com/Cantera/cantera/pull/660">#660</a>, <a href="https://github.com/Cantera/cantera/pull/733">#733</a>, <a href="https://github.com/Cantera/cantera/pull/735">#735</a>, <a href="https://github.com/Cantera/cantera/pull/762">#762</a>, <a href="https://github.com/Cantera/cantera/pull/787">#787</a>, <a href="https://github.com/Cantera/cantera/pull/790">#790</a>, <a href="https://github.com/Cantera/cantera/pull/806">#806</a>, <a href="https://github.com/Cantera/cantera/pull/815">#815</a>, <a href="https://github.com/Cantera/cantera/pull/864">#864</a>, <a href="https://github.com/cantera/cantera/commit/35be561d99c4ee8f544db4016849d94bf26b4df6"><code>35be561d99c4ee8f544db4016849d94bf26b4df6</code></a>, <a href="https://github.com/cantera/cantera/commit/27d9b6413a6b12a84947db72658c1785e8c1393f"><code>27d9b6413a6b12a84947db72658c1785e8c1393f</code></a>)</li> -<li>Build and test the sample programs / scripts as part of the CI process (<a href="https://github.com/cantera/cantera/commit/1ec9ce2c01da81479952dcc12140634d9bd4d9ff"><code>1ec9ce2c01da81479952dcc12140634d9bd4d9ff</code></a>, <a href="https://github.com/Cantera/cantera/pull/649">#649</a>, <a href="https://github.com/Cantera/cantera/pull/776">#776</a>, <a href="https://github.com/Cantera/cantera/pull/874">#874</a>, <a href="https://github.com/Cantera/cantera/pull/883">#883</a>, <a href="https://github.com/Cantera/cantera/pull/905">#905</a>, <a href="https://github.com/Cantera/cantera/pull/923">#923</a>, <a href="https://github.com/Cantera/cantera/pull/927">#927</a>)</li> -<li>Improve handling of phases where the intrinsic state variables are not temperature and density (<a href="https://github.com/Cantera/cantera/pull/720">#720</a>)</li> -<li>Improve detection and handling of errors in Chemkin input files (<a href="https://github.com/Cantera/cantera/pull/585">#585</a>, <a href="https://github.com/cantera/cantera/commit/b2acc43a813fd755a4b60bca87006dc7a72a74a0"><code>b2acc43a813fd755a4b60bca87006dc7a72a74a0</code></a>, <a href="https://github.com/cantera/cantera/commit/4f4a2bd07162a67ca96dcc9f514dbab29beedcfe"><code>4f4a2bd07162a67ca96dcc9f514dbab29beedcfe</code></a>, <a href="https://github.com/cantera/cantera/commit/d04fd8cc39cb9982aafe7cac28b58174b5fd6a81"><code>d04fd8cc39cb9982aafe7cac28b58174b5fd6a81</code></a>)</li> -<li>Consolidate and report all errors when adding reactions, instead of just failing on the first one (<a href="https://github.com/Cantera/cantera/pull/903">#903</a>, <a href="https://github.com/Cantera/cantera/pull/946">#946</a>)</li> -<li>Use 'Q' instead of 'X' for the quality (vapor fraction) of two-phase mixtures in Python (<a href="https://github.com/Cantera/cantera/pull/719">#719</a>)</li> -<li>Always use temperature of the "reacting" phase for interface kinetics (<a href="https://github.com/cantera/cantera/commit/6c82b61c3d8b6738a8a9edb5c062fa3c50423d96"><code>6c82b61c3d8b6738a8a9edb5c062fa3c50423d96</code></a>)</li> -<li>Make interface for setting parameters for Valves and PressureControllers more intuitive (<a href="https://github.com/Cantera/cantera/pull/667">#667</a>, <a href="https://github.com/Cantera/cantera/pull/682">#682</a>)</li> -<li>Add N2 to h2o2.yaml (<a href="https://github.com/Cantera/cantera/pull/959">#959</a>)</li> -<li>Make CVODES integrator 'max_time_step' a property in the Python module (<a href="https://github.com/Cantera/cantera/pull/731">#731</a>)</li> -<li>Switch CI to GitHub Actions (<a href="https://github.com/Cantera/cantera/pull/775">#775</a>, <a href="https://github.com/Cantera/cantera/pull/884">#884</a>, <a href="https://github.com/Cantera/cantera/pull/889">#889</a>, <a href="https://github.com/Cantera/cantera/pull/957">#957</a>)</li> -<li>Use experimentally-derived O2/O2- collision integral in ionized flames (<a href="https://github.com/Cantera/cantera/pull/552">#552</a>)</li> -<li>Consistently use CanteraError in Python examples (<a href="https://github.com/Cantera/cantera/pull/596">#596</a>, <a href="https://github.com/cantera/cantera/commit/05eaa0a5e4d0c73c5827f7f2c9bbd090d68e8c30"><code>05eaa0a5e4d0c73c5827f7f2c9bbd090d68e8c30</code></a>)</li> -<li>Add option to use case-sensitive species names (<a href="https://github.com/Cantera/cantera/pull/689">#689</a>)</li> -<li>Treat deprecation warnings issued from Python and C++ consistently (<a href="https://github.com/Cantera/cantera/pull/796">#796</a>)</li> -<li>Improve sample build scripts on maCOS (<a href="https://github.com/Cantera/cantera/pull/612">#612</a>)</li> -<li>Updated the 'diamond_cvd.py' example to include plotting the output (<a href="https://github.com/Cantera/cantera/pull/630">#630</a>)</li> -<li>Make GRI-3.0 mechanisms consistent with latest online version (<a href="https://github.com/Cantera/cantera/pull/718">#718</a>)</li> -<li>Follow Python naming convention for arguments to ThermoPhase.equilibrate (<a href="https://github.com/Cantera/cantera/pull/684">#684</a>)</li> -<li>Remove unused Chemkin input files from the source distribution (<a href="https://github.com/Cantera/cantera/pull/799">#799</a>)</li> -<li>Move heat_release_rate method to Python Kinetics class (<a href="https://github.com/Cantera/cantera/pull/810">#810</a>)</li> -<li>Automatically add 'negative_A' option for third body reactions when converting from Chemkin input (<a href="https://github.com/Cantera/cantera/pull/822">#822</a>)</li> -<li>Allow negative pre-exponential factor for falloff reactions (<a href="https://github.com/Cantera/cantera/pull/868">#868</a>)</li> -<li>Search current working directory before built-in data directories when using Python (<a href="https://github.com/Cantera/cantera/pull/792">#792</a>)</li> -<li>Check for additional invalid string-to-double conversions when parsing composition strings (<a href="https://github.com/cantera/cantera/commit/84535483f9ba768c72196fccf2e9ac2c1ee9d0dd"><code>84535483f9ba768c72196fccf2e9ac2c1ee9d0dd</code></a>)</li> -<li>The default branch for the Cantera Git repository is now named 'main' (<a href="https://github.com/Cantera/cantera/pull/890">#890</a>)</li> -<li>Include more significant digits for Redlich-Kwong coefficients when converting from CTI to XML (<a href="https://github.com/cantera/cantera/commit/ec7f779434d705ea5097abdc88a723e1dd4c96e8"><code>ec7f779434d705ea5097abdc88a723e1dd4c96e8</code></a>)</li> -</ul> - -<h2>Bugs fixed:</h2> -<ul> -<li>Fixed various compilation issues on specific platforms and with certain SCons/compiler options (<a href="https://github.com/Cantera/cantera/pull/561">#561</a>, <a href="https://github.com/Cantera/cantera/pull/572">#572</a>, <a href="https://github.com/Cantera/cantera/pull/601">#601</a>, <a href="https://github.com/Cantera/cantera/pull/648">#648</a>, <a href="https://github.com/Cantera/cantera/pull/661">#661</a>, <a href="https://github.com/Cantera/cantera/pull/674">#674</a>, <a href="https://github.com/Cantera/cantera/pull/676">#676</a>, <a href="https://github.com/Cantera/cantera/pull/685">#685</a>, <a href="https://github.com/Cantera/cantera/pull/742">#742</a>, <a href="https://github.com/Cantera/cantera/pull/765">#765</a>, <a href="https://github.com/Cantera/cantera/pull/779">#779</a>, <a href="https://github.com/Cantera/cantera/pull/803">#803</a>, <a href="https://github.com/Cantera/cantera/pull/824">#824, <a href="https://github.com/Cantera/cantera/pull/879">#879</a>, <a href="https://github.com/Cantera/cantera/pull/891">#891</a>, <a href="https://github.com/Cantera/cantera/pull/918">#918</a>, <a href="https://github.com/Cantera/cantera/pull/960">#960</a>, <a href="https://github.com/Cantera/cantera/pull/962">#962</a>, <a href="https://github.com/Cantera/cantera/pull/973">#973</a>, <a href="https://github.com/cantera/cantera/commit/46b7cf180a9c10bf27330de804353c9ded792b7f"><code>46b7cf180a9c10bf27330de804353c9ded792b7f</code></a>)</li> -<li>Fix handling of local quantity units rate for Chebyshev rate constants when converting Chemkin input files (<a href="https://github.com/Cantera/cantera/pull/600">#600</a>)</li> -<li>Fix setting of Soret and multicomponent diffusion options after exceptions when using the "auto" option to Sim1D.solve (<a href="https://github.com/Cantera/cantera/pull/631">#631</a>)</li> -<li>Disable free flame domain width check when auto=False (<a href="https://github.com/Cantera/cantera/pull/690">#690</a>)</li> -<li>Allow setting beta = 0 for electrochemical reactions (<a href="https://github.com/Cantera/cantera/pull/955">#955</a>)</li> -<li>Fix Redlich-Kwong phase to not use the element potential equilibrium solver (<a href="https://github.com/Cantera/cantera/pull/898">#898</a>)</li> -<li>Fix erroneously-rounded transport coefficients in input files derived from GRI 3.0 (<a href="https://github.com/Cantera/cantera/pull/598">#598</a>)</li> -<li>Use correct phase state after Reactor mass flow rate evaluation (<a href="https://github.com/Cantera/cantera/pull/651">#651</a>)</li> -<li>Avoid NaN in entropy with small negative mass fractions (<a href="https://github.com/Cantera/cantera/pull/686">#686</a>)</li> -<li>Fix conversion of Chemkin input files with surface reactions with explicit reverse rates (<a href="https://github.com/Cantera/cantera/pull/754">#754</a>)</li> -<li>Fix conditional property updates in IonGasTransport (<a href="https://github.com/Cantera/cantera/pull/568">#568</a>)</li> -<li>Fix Chebyshev rate evaluation with only 1 point in T or P (<a href="https://github.com/Cantera/cantera/pull/706">#706</a>)</li> -<li>Check for non-existent species in reaction orders when adding reactions (<a href="https://github.com/cantera/cantera/commit/e4362d37e7cf2d527a14c6202868b5ffd76f2436"><code>e4362d37e7cf2d527a14c6202868b5ffd76f2436</code></a>)</li> -<li>Fix various edge cases for saturated PureFluid states (<a href="https://github.com/Cantera/cantera/pull/907">#907</a>)</li> -<li>Fix comparisons of non-numeric text in test_problems (<a href="https://github.com/Cantera/cantera/pull/785">#785</a>)</li> -<li>Prevent overwriting of pre-existing extra SolutionArray columns (<a href="https://github.com/Cantera/cantera/pull/820">#820</a>)</li> -<li>Fix slicing of SolutionArray (<a href="https://github.com/Cantera/cantera/pull/816">#816</a>, <a href="https://github.com/Cantera/cantera/pull/837">#837</a>)</li> -<li>Prevent erroneous creation of standalone Kinetics and Transport objects in Python (<a href="https://github.com/Cantera/cantera/pull/845">#845</a>)</li> -<li>Ensure that the mass flow rate returned by FlowDevice objects is correct after a call to ReactorNet::advance (<a href="https://github.com/Cantera/cantera/pull/886">#886</a>)</li> -<li>Fix indexed assignment of 'extra' columns in SolutionArray (<a href="https://github.com/Cantera/cantera/pull/838">#838</a>)</li> -<li>Fix handling of reaction units settings not on last line when convert Chemkin input files (<a href="https://github.com/cantera/cantera/commit/540777c32b57d99c61d0bf1e2cc825353be4846b"><code>540777c32b57d99c61d0bf1e2cc825353be4846b</code></a>)</li> -<li>Fix over-zealous detection of section 'end' labels when converting Chemkin input files (<a href="https://github.com/cantera/cantera/commit/e3424d8ed49f5f7611bc94933109292d32b732ec"><code>e3424d8ed49f5f7611bc94933109292d32b732ec</code></a>)</li> -<li>Fix building and installing the minimal Python package (<a href="https://github.com/Cantera/cantera/pull/928">#928</a>, <a href="https://github.com/Cantera/cantera/pull/974">#974</a>)</li> -<li>Check for a valid species index in ThermoPhase::species() (<a href="https://github.com/Cantera/cantera/pull/949">#949</a>)</li> -<li>Fix some corner cases in Sim1D::setFixedTemperature (<a href="https://github.com/Cantera/cantera/pull/936">#936</a>)</li> -<li>Retain user-specified products in counterflow premixed flame when using "auto" option (<a href="https://github.com/cantera/cantera/commit/b633544477facbb9f4390b380a2e7edefac79010"><code>b633544477facbb9f4390b380a2e7edefac79010</code></a>)</li> -<li>Fix refinement check in ic_engine.py example (<a href="https://github.com/cantera/cantera/commit/d9b95b2efbe6c512f00f72fe2e0bf4fda76ba7e6"><code>d9b95b2efbe6c512f00f72fe2e0bf4fda76ba7e6</code></a>)</li> -<li>Fix issues with Blasius BVP example, and install it with other C++ samples (<a href="https://github.com/cantera/cantera/commit/dc09040274370149c6dafb05e126e875e0db6549"><code>dc09040274370149c6dafb05e126e875e0db6549</code></a>, <a href="https://github.com/cantera/cantera/commit/600580ead4906339fee0bae6a80356ec5d3a4191"><code>600580ead4906339fee0bae6a80356ec5d3a4191</code></a>, <a href="https://github.com/cantera/cantera/commit/c26db356e3523c89878e8a6f5b5cd5d64dc32b73"><code>c26db356e3523c89878e8a6f5b5cd5d64dc32b73</code></a>, <a href="https://github.com/cantera/cantera/commit/b9a5913af01cb316734f3742d111614fc0a957b1"><code>b9a5913af01cb316734f3742d111614fc0a957b1</code></a>, <a href="https://github.com/cantera/cantera/commit/22efbe25dc97c2e42960c7cf09335ca546ec8ef5"><code>22efbe25dc97c2e42960c7cf09335ca546ec8ef5</code></a>, <a href="https://github.com/cantera/cantera/commit/8c213da93226859e741ac108333f1b08c4db7b24"><code>8c213da93226859e741ac108333f1b08c4db7b24</code></a>)</li> -</ul> - -<h2>Documentation updates:</h2> -<ul> -<li>Fix errors in equations (<a href="https://github.com/Cantera/cantera/pull/557">#557, <a href="https://github.com/Cantera/cantera/pull/970">#970</a>, <a href="https://github.com/cantera/cantera/commit/3ff5d87b815eb6c299745954947ff566e55066cc"><code>3ff5d87b815eb6c299745954947ff566e55066cc</code></a>, <a href="https://github.com/cantera/cantera/commit/c1d721dc94b4f5f8dedc47a4d8066bb24d761599"><code>c1d721dc94b4f5f8dedc47a4d8066bb24d761599</code></a>)</li> -<li>Improve "offline" builds of API documentation (<a href="https://github.com/Cantera/cantera/pull/562">#562</a>)</li> -<li>Document required versions of Cantera and dependencies for Python examples (<a href="https://github.com/Cantera/cantera/pull/729">#729</a>, <a href="https://github.com/Cantera/cantera/pull/756">#756</a>)</li> -<li>Update AUTHORS list to include authors from all Cantera organization repos (<a href="https://github.com/Cantera/cantera/pull/573">#573</a>)</li> -<li>Fix various typos and other issues (<a href="https://github.com/Cantera/cantera/pull/591">#591</a>, <a href="https://github.com/Cantera/cantera/pull/627">#627</a>, <a href="https://github.com/Cantera/cantera/pull/636">#636</a>, <a href="https://github.com/Cantera/cantera/pull/673">#673</a>, <a href="https://github.com/Cantera/cantera/pull/709">#709</a>, <a href="https://github.com/Cantera/cantera/pull/726">#726</a>, <a href="https://github.com/Cantera/cantera/pull/744">#744</a>, <a href="https://github.com/Cantera/cantera/pull/770">#770</a>, <a href="https://github.com/Cantera/cantera/pull/771">#771</a>, <a href="https://github.com/Cantera/cantera/pull/781">#781</a>, <a href="https://github.com/Cantera/cantera/pull/790">#790</a>, <a href="https://github.com/Cantera/cantera/pull/793">#793</a>, <a href="https://github.com/Cantera/cantera/pull/939">#939</a>, <a href="https://github.com/cantera/cantera/commit/50997a165119ccb997206e4738750621510bbd79"><code>50997a165119ccb997206e4738750621510bbd79</code></a>, <a href="https://github.com/cantera/cantera/commit/9f5dfbdb1273c05d176c58ab62fe7dbb12d24a94"><code>9f5dfbdb1273c05d176c58ab62fe7dbb12d24a94</code></a>, <a href="https://github.com/cantera/cantera/commit/442433ad3738ecf17052811bd5751d77666b558b"><code>442433ad3738ecf17052811bd5751d77666b558b</code></a>, <a href="https://github.com/Cantera/cantera/pull/975">#975</a>, <a href="https://github.com/Cantera/cantera/pull/976">#976</a>)</li> -</ul> diff --git a/pages/documentation/release_notes/v2.6.0.md b/pages/documentation/release_notes/v2.6.0.md deleted file mode 100644 index 4b9ef6050..000000000 --- a/pages/documentation/release_notes/v2.6.0.md +++ /dev/null @@ -1,101 +0,0 @@ -<!-- -.. title: Cantera 2.6.0 -.. slug: v2.6.0 -.. date: 2022-05-01 -.. tags: -.. category: -.. link: -.. description: -.. type: text ---> - -# Cantera 2.6.0 - -Published on May 1, 2022 | [Full release on Github](https://github.com/Cantera/cantera/releases/tag/v2.6.0) - -The Cantera development team is pleased to announce the availability of Cantera 2.6.0. There have been over 1400 commits to Cantera since the last version, 2.5.1, which was released in February 2021. We have closed or merged [162 pull requests](https://github.com/Cantera/cantera/pulls?q=is%3Apr+merged%3A2021-02-13..2022-05-01+is%3Aclosed) and closed [101 issues](https://github.com/Cantera/cantera/issues?page=4&q=is%3Aissue+closed%3A2021-02-13..2022-05-01+is%3Aclosed). - -## New features, bug fixes, and other changes - -### Highlights -- Major redesign of how reaction rates are handled internally to improve extensibility and enable new capabilities ([E#63](https://github.com/Cantera/enhancements/issues/63), [E#87](https://github.com/Cantera/enhancements/issues/87), [#982](https://github.com/Cantera/cantera/pull/982), [#995](https://github.com/Cantera/cantera/pull/995), [#1061](https://github.com/Cantera/cantera/pull/1061), [#1101](https://github.com/Cantera/cantera/pull/1101), [#1151](https://github.com/Cantera/cantera/pull/1151), [#1153](https://github.com/Cantera/cantera/pull/1153), [#1181](https://github.com/Cantera/cantera/pull/1181), [#1183](https://github.com/Cantera/cantera/pull/1183), [#1184](https://github.com/Cantera/cantera/pull/1184), [#1187](https://github.com/Cantera/cantera/pull/1187), [#1202](https://github.com/Cantera/cantera/pull/1202), [#1216](https://github.com/Cantera/cantera/pull/1216), [#1223](https://github.com/Cantera/cantera/pull/1223), [#1225](https://github.com/Cantera/cantera/pull/1225), [#1256](https://github.com/Cantera/cantera/pull/1256), [#1257](https://github.com/Cantera/cantera/pull/1257)) -- Enable delegation of reactor implementation to user-provided Python classes ([`custom2.py`](https://github.com/Cantera/cantera/blob/main/interfaces/cython/cantera/examples/reactors/custom2.py), [#1003](https://github.com/Cantera/cantera/pull/1003)) -- Enable serialization of Cantera objects to YAML ([`mechanism_reduction.py`](https://github.com/Cantera/cantera/blob/main/interfaces/cython/cantera/examples/kinetics/mechanism_reduction.py), [#984](https://github.com/Cantera/cantera/pull/984), [#1014](https://github.com/Cantera/cantera/pull/1014), [#1031](https://github.com/Cantera/cantera/pull/1031)) -- Implement pickling of Python Solution objects ([#692](https://github.com/Cantera/cantera/pull/692)) -- Add [PyPI](https://pypi.org/project/Cantera/) package for Cantera, installable with `pip`([#1075](https://github.com/Cantera/cantera/pull/1075), [#1239](https://github.com/Cantera/cantera/pull/1239), [#1240](https://github.com/Cantera/cantera/pull/1240), [#1232](https://github.com/Cantera/cantera/pull/1232), [#1261](https://github.com/Cantera/cantera/pull/1261)) -- Implement Peng-Robinson equation of state for real gases ([#1047](https://github.com/Cantera/cantera/pull/1047), [#1141](https://github.com/Cantera/cantera/pull/1141), [#1180](https://github.com/Cantera/cantera/pull/1180)) -- Add Blowers-Masel reaction rate parameterization for gas phase and interface kinetics ([`blowers-masel.py`](https://github.com/Cantera/cantera/blob/main/interfaces/cython/cantera/examples/kinetics/blowers_masel.py), [#987](https://github.com/Cantera/cantera/pull/987)) -- Add calculation of sparse, analytical Jacobians for gas kinetics ([`derivative_speed.cpp`](https://github.com/Cantera/cantera/blob/main/samples/cxx/jacobian/derivative_speed.cpp), [#1088](https://github.com/Cantera/cantera/pull/1088), [#1089](https://github.com/Cantera/cantera/pull/1089), [#1212](https://github.com/Cantera/cantera/pull/1212)) -- Add new phase type and reaction rate parameterizations for plasmas with independent electron temperature ([#1099](https://github.com/Cantera/cantera/pull/1099), [#1166](https://github.com/Cantera/cantera/pull/1166), [#1190](https://github.com/Cantera/cantera/pull/1190)) - -### New features -- Simplify creation of interface phases and their adjacent bulk phases ([#1169](https://github.com/Cantera/cantera/pull/1169), [#1247](https://github.com/Cantera/cantera/pull/1247)) -- Add Tsang "falloff" function [#1090](https://github.com/Cantera/cantera/pull/1090) -- Add option to allow unnormalized and/or negative mass/mole fractions in SolutionArray / 1D flame importers [#1037](https://github.com/Cantera/cantera/pull/1037) -- Added access functions to polynomial fits of gas transport properties [#817](https://github.com/Cantera/cantera/pull/817), [#1077](https://github.com/Cantera/cantera/pull/1077) -- Add dilution options to equivalence ratio functions in Python [#1206](https://github.com/Cantera/cantera/pull/1206) -- Make rate coefficient and standard concentration units available in Python [#1076](https://github.com/Cantera/cantera/pull/1076) -- Add creation of Species from Python dict [#1179](https://github.com/Cantera/cantera/pull/1179) -- Add thermal conductivity to DustyGas in Python [#988](https://github.com/Cantera/cantera/pull/988) -- Add `set_mixture_fraction` method to `SolutionArray` [#1242](https://github.com/Cantera/cantera/pull/1242) -- Exposed some additional functions to the Fortran interface [#1154](https://github.com/Cantera/cantera/pull/1154) -- New C++ custom ODEs example [#922](https://github.com/Cantera/cantera/pull/922) -- Added a Python version of the Matlab lithium ion battery example [#1263](https://github.com/Cantera/cantera/pull/1263) -- Add support for Sundials 6.0 [#1162](https://github.com/Cantera/cantera/pull/1162) - -### Changes to existing capabilities -- Use YAML for saving and loading 1D flame simulations, replacing the XML output format [#1112](https://github.com/Cantera/cantera/pull/1112), [#1140](https://github.com/Cantera/cantera/pull/1140) -- Use normal sign convention for reactor heat transfer [#1156](https://github.com/Cantera/cantera/pull/1156) -- Separate third-body concentration term from rate constant for three body reactions [#1084](https://github.com/Cantera/cantera/pull/1084) -- Translate C++ warnings to Python [#1201](https://github.com/Cantera/cantera/pull/1201) -- Refactor SCons option handling and automatically extract compilation options for website documentation [#1137](https://github.com/Cantera/cantera/pull/1137) -- Automatically use dependencies from and install into an active Conda environment [#1191](https://github.com/Cantera/cantera/pull/1191) -- Include header description in when converting from CTI to YAML [#1205](https://github.com/Cantera/cantera/pull/1205) -- Use of deprecated XML or CTI formats now actively issues warnings [#1159](https://github.com/Cantera/cantera/pull/1159) -- Support legacy ruamel.yaml loaders [#1060](https://github.com/Cantera/cantera/pull/1060) -- Update examples to use "h2o2.yaml" instead of GRI 3.0 [#1109](https://github.com/Cantera/cantera/pull/1109) -- Prevent inadvertent attribute assignment in Quantity [#1124](https://github.com/Cantera/cantera/pull/1124) -- Fix issues with composition strings and kinetics model of "None" in cti2yaml [#1127](https://github.com/Cantera/cantera/pull/1127) -- Deprecate shell setup scripts (`setup_cantera`) [#1189](https://github.com/Cantera/cantera/pull/1189) -- Replace deprecated yaml.safe_load / simplify paths [#1049](https://github.com/Cantera/cantera/pull/1049) -- Read YAML using C++ newSolution in Python / access root level data [#1129](https://github.com/Cantera/cantera/pull/1129) -- Improve YAML formatting of floating point values and multiline strings [#1133](https://github.com/Cantera/cantera/pull/1133) -- Automatically detect unspecified third-body collision partners [#1015](https://github.com/Cantera/cantera/pull/1015) -- Various compilation, build system, and test infrastructure updates [#979](https://github.com/Cantera/cantera/pull/979), [#994](https://github.com/Cantera/cantera/pull/994), [#1000](https://github.com/Cantera/cantera/pull/1000), [#1004](https://github.com/Cantera/cantera/pull/1004), [#1012](https://github.com/Cantera/cantera/pull/1012), [#1020](https://github.com/Cantera/cantera/pull/1020), [#1025](https://github.com/Cantera/cantera/pull/1025), [#1034](https://github.com/Cantera/cantera/pull/1034), [#1043](https://github.com/Cantera/cantera/pull/1043), [#1056](https://github.com/Cantera/cantera/pull/1056), [#1062](https://github.com/Cantera/cantera/pull/1062), [#1145](https://github.com/Cantera/cantera/pull/1145), [#1158](https://github.com/Cantera/cantera/pull/1158), [#1102](https://github.com/Cantera/cantera/pull/1102), [#1119](https://github.com/Cantera/cantera/pull/1119), [#1122](https://github.com/Cantera/cantera/pull/1122), [#1144](https://github.com/Cantera/cantera/pull/1144). [#1167](https://github.com/Cantera/cantera/pull/1167), [#1172](https://github.com/Cantera/cantera/pull/1172), [#1176](https://github.com/Cantera/cantera/pull/1176), [#1178](https://github.com/Cantera/cantera/pull/1178), [#1197](https://github.com/Cantera/cantera/pull/1197), [#1208](https://github.com/Cantera/cantera/pull/1208), [#1222](https://github.com/Cantera/cantera/pull/1222), [#1229](https://github.com/Cantera/cantera/pull/1229), [#1241](https://github.com/Cantera/cantera/pull/1241), [#1268](https://github.com/Cantera/cantera/pull/1268) -- Various documentation updates [#983](https://github.com/Cantera/cantera/pull/983), [#1002](https://github.com/Cantera/cantera/pull/1002), [#1022](https://github.com/Cantera/cantera/pull/1022), [#1032](https://github.com/Cantera/cantera/pull/1032), [#1045](https://github.com/Cantera/cantera/pull/1045), [#1065](https://github.com/Cantera/cantera/pull/1065), [#1121](https://github.com/Cantera/cantera/pull/1121), [#1142](https://github.com/Cantera/cantera/pull/1142), [#1152](https://github.com/Cantera/cantera/pull/1152), [#1196](https://github.com/Cantera/cantera/pull/1196), [#1200](https://github.com/Cantera/cantera/pull/1200), [#1227](https://github.com/Cantera/cantera/pull/1227), [#1231](https://github.com/Cantera/cantera/pull/1231), [#1234](https://github.com/Cantera/cantera/pull/1234), [#1249](https://github.com/Cantera/cantera/pull/1249), [#1255](https://github.com/Cantera/cantera/pull/1255), [#1264](https://github.com/Cantera/cantera/pull/1264) - -### Bugs fixed -- Fix Redlich-Kwong partial molar properties [#1218](https://github.com/Cantera/cantera/pull/1218) -- Fix pressure dependence in IdealSolidSolnPhase::getPartialMolarEnthalpies [#1087](https://github.com/Cantera/cantera/pull/1087) -- Fix evaluation of delta-star polynomials [#1125](https://github.com/Cantera/cantera/pull/1125) -- Consistently use physical concentrations when calculating third body and falloff reaction rates, for both specifically enumerated efficiencies and generic third body colliders [#968](https://github.com/Cantera/cantera/pull/968) -- Add check for sticking coefficient more than 1 [#1038](https://github.com/Cantera/cantera/pull/1038) -- Fix typo in equivalenceRatio.py that resulted in printing wrong results [#1173](https://github.com/Cantera/cantera/pull/1173) -- Fix memory error when deallocating Python reaction rate wrappers [#1030](https://github.com/Cantera/cantera/pull/1030) -- Prevent segmentation fault when initializing standalone Reactor objects [#1063](https://github.com/Cantera/cantera/pull/1063) -- Fix extinction temperature definition in diffusion_flame_extinction.py example [#1066](https://github.com/Cantera/cantera/pull/1066) -- Fix handling of 'CK_Multi' transport model in flame simulations [#1069](https://github.com/Cantera/cantera/pull/1069) -- Fix issues with import of SolutionArray from CSV [#1074](https://github.com/Cantera/cantera/pull/1074) -- Fix SolutionArray.append [#1086](https://github.com/Cantera/cantera/pull/1086) -- Fix 1D solver errors when reporting singular Jacobian and use of non-default tolerances after automatic grid expansion [#1103](https://github.com/Cantera/cantera/pull/1103) -- Suppress output from setEnergy.m [#1106](https://github.com/Cantera/cantera/pull/1106) -- Fix using reactors with both surface and gas phase chemistry with YAML input [#981](https://github.com/Cantera/cantera/pull/981) -- Fix saving 1D output when radiative_heat_loss is enabled [#993](https://github.com/Cantera/cantera/pull/993) -- Fix CTI to YAML conversion for transport='None' [#997](https://github.com/Cantera/cantera/pull/997) -- Fix handling of CK mechanisms with '+M' in PLOG reaction equations [#1252](https://github.com/Cantera/cantera/pull/1252) -- Fix detection of skipped/undeclared species in three body reactions [#1027](https://github.com/Cantera/cantera/pull/1027) -- Fix invalid unchecked cast to StFlow [#1226](https://github.com/Cantera/cantera/pull/1226) -- Fix `SolutionArray` extra slice [#1204](https://github.com/Cantera/cantera/pull/1204) -- Check for valid component name when setting reactor advance limits [#1215](https://github.com/Cantera/cantera/pull/1215) -- Fix incorrect temperature bounds and missing entries in NASA_condensed.yaml [#1248](https://github.com/Cantera/cantera/pull/1248), [#1250](https://github.com/Cantera/cantera/pull/1250) -- Fix logic error in CanteraTest.assertNear [#1120](https://github.com/Cantera/cantera/pull/1120) -- Fix various compilation / installation issues [#980](https://github.com/Cantera/cantera/pull/980), [#1011](https://github.com/Cantera/cantera/pull/1011), [#1052](https://github.com/Cantera/cantera/pull/1052), [#1057](https://github.com/Cantera/cantera/pull/1057), [#1100](https://github.com/Cantera/cantera/pull/1100), [#1105](https://github.com/Cantera/cantera/pull/1105), [#1107](https://github.com/Cantera/cantera/pull/1107), [#1110](https://github.com/Cantera/cantera/pull/1110), [#1116](https://github.com/Cantera/cantera/pull/1116), [#1123](https://github.com/Cantera/cantera/pull/1123), [#1148](https://github.com/Cantera/cantera/pull/1148), [#1161](https://github.com/Cantera/cantera/pull/1161), [#1168](https://github.com/Cantera/cantera/pull/1168), [#1171](https://github.com/Cantera/cantera/pull/1171), [#1265](https://github.com/Cantera/cantera/pull/1265) - -The complete list of changes can be found on the Cantera Wiki page: https://github.com/Cantera/cantera/wiki/Cantera-2.6.0-Changelog - -## 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. - -## 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) diff --git a/pages/documentation/release_notes/v3.0.0.md b/pages/documentation/release_notes/v3.0.0.md deleted file mode 100644 index 4ee63ec60..000000000 --- a/pages/documentation/release_notes/v3.0.0.md +++ /dev/null @@ -1,107 +0,0 @@ -<!-- -.. title: Cantera 3.0.0 -.. slug: v3.0.0 -.. date: 2023-08-22 -.. type: text ---> - -# Cantera 3.0.0 - -Published on August 22, 2023 | [Full release on GitHub](https://github.com/Cantera/cantera/releases/tag/v3.0.0) - -The Cantera development team is pleased to announce the availability of Cantera 3.0.0. There have been over [1400 commits](https://github.com/Cantera/cantera/wiki/Cantera-3.0.0-Changelog) to Cantera since the last version, 2.6.0, which was released in May 2022. We have closed or merged [192 pull requests](https://github.com/Cantera/cantera/pulls?q=is%3Apr+merged%3A2022-05-01..2023-08-22+is%3Aclosed) and closed [111 issues](https://github.com/Cantera/cantera/issues?q=is%3Aissue+closed%3A2022-05-01..2023-08-22+is%3Aclosed). Instructions for installing Cantera 3.0 are available on the [Cantera website](https://cantera.org/install/index.html). - -## Highlights - -- Major performance enhancements for reactor network calculations with large kinetic mechanisms. This comes from a new formulation for the reactor governing equations using species moles (rather than mass fractions) used together with a sparse, iterative solver in the ODE integrator that makes use of a semi-analytical Jacobian. ([`preconditioned_integration.py`](https://cantera.org/examples/python/reactors/preconditioned_integration.py.html), [#1010](https://github.com/Cantera/cantera/pull/1010), [#1344](https://github.com/Cantera/cantera/pull/1344), [#1363](https://github.com/Cantera/cantera/pull/1363), [#1377](https://github.com/Cantera/cantera/pull/1377), [#1411](https://github.com/Cantera/cantera/pull/1411)) -- Introduce `ExtensibleRate` Python class that can be used to implement new reaction rate parameterizations in Python, with parameters defined in YAML input files. These rate types can be used even when the main user application is not written in Python. ([class `ExtensibleRate`](https://cantera.org/documentation/docs-3.0/sphinx/html/cython/kinetics.html#extensiblerate), [`custom_reactions.py`](https://cantera.org/examples/python/kinetics/custom_reactions.py.html), [#1382](https://github.com/Cantera/cantera/pull/1382), [#1417](https://github.com/Cantera/cantera/pull/1417), [#1456](https://github.com/Cantera/cantera/pull/1456), [#1478](https://github.com/Cantera/cantera/pull/1478), [#1494](https://github.com/Cantera/cantera/pull/1494), [#1499](https://github.com/Cantera/cantera/pull/1499)) -- Introduce a C++ `SolutionArray` class, which is now used as the backend for the Python `SolutionArray` class ([E#137](https://github.com/Cantera/enhancements/issues/137), [#1385](https://github.com/Cantera/cantera/pull/1385), [#1426](https://github.com/Cantera/cantera/pull/1426), [#1458](https://github.com/Cantera/cantera/pull/1458), [#1462](https://github.com/Cantera/cantera/pull/1462), [#1464](https://github.com/Cantera/cantera/pull/1464), [#1508](https://github.com/Cantera/cantera/pull/1508), [#1520](https://github.com/Cantera/cantera/pull/1520), [#1547](https://github.com/Cantera/cantera/pull/1547), [#1585](https://github.com/Cantera/cantera/pull/1585)) -- Add "native" support for HDF5 as an input/output format for `SolutionArray` and 1D flames ([E#166](https://github.com/Cantera/enhancements/issues/166), [`flame_initial_guess.py`](https://cantera.org/examples/python/onedim/flame_initial_guess.py.html)) -- Add a new thermo model, `coverage-dependent-surface` for representing surfaces where the enthalpy, entropy, and heat capacity of each species may depend on its coverage and the coverage of other species in the phase. ([class `CoverageDependentSurfPhase`](https://cantera.org/documentation/docs-3.0/doxygen/html/db/d25/classCantera_1_1CoverageDependentSurfPhase.html#details), [E#59](https://github.com/Cantera/enhancements/issues/59), [#1135](https://github.com/Cantera/cantera/pull/1135), [#1471](https://github.com/Cantera/cantera/pull/1471), [#1529](https://github.com/Cantera/cantera/pull/1529), [#1583](https://github.com/Cantera/cantera/pull/1583)) -- Add support for surface chemistry to the plug flow reactor model ([classs `FlowReactor`](https://cantera.org/documentation/docs-3.0/sphinx/html/cython/zerodim.html#flowreactor), [`1D_pfr_surfchem.py`](https://cantera.org/examples/python/surface_chemistry/1D_pfr_surfchem.py.html), [`surf_pfr.py`](https://cantera.org/examples/python/reactors/surf_pfr.py.html), [#1490](https://github.com/Cantera/cantera/pull/1490)) -- Add support for using real gas models (Redlich-Kwong and Peng-Robinson) with the 1D flame solver ([E#109](https://github.com/Cantera/enhancements/issues/109), [#1079](https://github.com/Cantera/cantera/pull/1079)) -- Introduction of the `yaml2ck` script, which converts Cantera's YAML mechanism format into the legacy Chemkin format. ([`yaml2ck.py`](https://cantera.org/documentation/docs-3.0/sphinx/html/cython/yaml_conversion.html), [E#52](https://github.com/Cantera/enhancements/issues/52), [#1286](https://github.com/Cantera/cantera/pull/1286), [#1365](https://github.com/Cantera/cantera/pull/1365), [#1420](https://github.com/Cantera/cantera/pull/1420)) -- Add an experimental Python module where Cantera returns dimensional values as quantities using the `pint` package. This is currently available only for thermo methods ([module `cantera.with_units`](https://cantera.org/documentation/docs-3.0/sphinx/html/cython/units.html), [`isentropic_units.py`](https://cantera.org/examples/python/thermo/isentropic_units.py.html), [`rankine_units.py`](https://cantera.org/examples/python/thermo/rankine_units.py.html), [`sound_speed_units.py`](https://cantera.org/examples/python/thermo/sound_speed_units.py.html), [E#3](https://github.com/Cantera/enhancements/issues/3), [#991](https://github.com/Cantera/cantera/pull/991), [#1569](https://github.com/Cantera/cantera/pull/1569)) -- Preview release of a new Matlab toolbox, with a rewritten API that makes use of modern Matlab features and replaces the difficult-to-maintain MEX-file based backend with one based on using `calllib` to interact directly with the Cantera C interface. (For the adventurous, see [`README.md`](https://github.com/Cantera/cantera/blob/main/interfaces/matlab_experimental/readme.md), [E#32](https://github.com/Cantera/enhancements/issues/32), [#1182](https://github.com/Cantera/cantera/pull/1182), [#1496](https://github.com/Cantera/cantera/pull/1496), [#1498](https://github.com/Cantera/cantera/pull/1498)) -- Preview release of a new C# interface. See [`README.md`](https://github.com/Cantera/cantera/blob/main/interfaces/dotnet/README.md) for more on what's implemented and how to contribute ([#1331](https://github.com/Cantera/cantera/pull/1331), [#1401](https://github.com/Cantera/cantera/pull/1401)) - -## New features - -- Add support for polynomial dependency of activation energy on surface species coverages ([documentation](https://cantera.org/documentation/docs-3.0/sphinx/html/yaml/reactions.html#interface-arrhenius), [#1495](https://github.com/Cantera/cantera/pull/1495)) -- Add speed of sound property to `ThermoPhase` objects ([`sound_speed.py`](https://cantera.org/examples/python/thermo/sound_speed.py.html), [#1491](https://github.com/Cantera/cantera/pull/1491)) -- Implemented isothermal compressibility and thermal expansion coefficient calculations for Redlich-Kwong and Peng-Robinson equations of state ([E#122](https://github.com/Cantera/enhancements/issues/122), [#1421](https://github.com/Cantera/cantera/pull/1421)) -- Add `interfaceCurrent` (C++) and `interface_current` methods to `Kinetics` objects ([#1398](https://github.com/Cantera/cantera/pull/1398)) -- Add molecular weight attribute to `Species` objects ([#1266](https://github.com/Cantera/cantera/pull/1266)) -- Add `set_equivalence_ratio` and `set_mixture_fraction` methods to Python `Quantity` objects ([#1517](https://github.com/Cantera/cantera/pull/1517)) -- Add array size methods to Python `SolutionArray` class ([#1284](https://github.com/Cantera/cantera/pull/1284)) -- Add `Solution` class to `clib` ([#1448](https://github.com/Cantera/cantera/pull/1448), [#1600](https://github.com/Cantera/cantera/pull/1600)) -- Introduce factory for creating 1D domains (`newDomain` in C++, `domain_new` in `clib`) ([#1445](https://github.com/Cantera/cantera/pull/1445)) -- Introduce factory for creating functor objects (`newFunc1` in C++; `func_new_basic`, `func_new_advanced`, `func_new_compound`, and `func_new_modified` in `clib`; and `Func1.cxx_functor` in Python) ([documentation](https://cantera.org/documentation/docs-3.0/doxygen/html/dc/d4c/group__func1.html), [#1513](https://github.com/Cantera/cantera/pull/1513), [#1521](https://github.com/Cantera/cantera/pull/1521)) -- Provide a more complete interface to the C++ `Units` class in Python ([#1285](https://github.com/Cantera/cantera/pull/1285)) -- Add a sample program demonstrating the use of the Cantera C interface, `clib` ([#1454](https://github.com/Cantera/cantera/pull/1454)) -- Add an example of modelling a porous media burner using the `ExtensibleReactor` class ([`PorousMediaBurner.py`](https://cantera.org/examples/python/reactors/PorousMediaBurner.py.html), [#1443](https://github.com/Cantera/cantera/pull/1443)) -- Add an example demonstrating saving and loading of 1D flame simulations and restarting with different initial guesses ([`flame_initial_guess.py`](https://cantera.org/examples/python/onedim/flame_initial_guess.py.html), [#1293](https://github.com/Cantera/cantera/pull/1293)) -- The test suite now includes a comprehensive set of thermodynamic consistency tests for all phase models ([E#114](https://github.com/Cantera/enhancements/issues/114), [#1299](https://github.com/Cantera/cantera/pull/1299), [#1501](https://github.com/Cantera/cantera/pull/1501)) -- Consolidate literature references in the C++ documentation into a [bibliography](https://cantera.org/documentation/docs-3.0/doxygen/html/d0/de3/citelist.html) ([#1550](https://github.com/Cantera/cantera/pull/1550), [#1575](https://github.com/Cantera/cantera/pull/1575)) -- Enable linking to the Cantera shared library on Windows ([E#140](https://github.com/Cantera/enhancements/issues/140), [#1429](https://github.com/Cantera/cantera/pull/1429)) -- Split up compilation of the Python module to allow parallel builds and faster incremental builds ([#1334](https://github.com/Cantera/cantera/pull/1334), [#1484](https://github.com/Cantera/cantera/pull/1484)) -- Automatically detect and use optimized BLAS/LAPACK libraries when compiling ([E#144](https://github.com/Cantera/enhancements/issues/144), [#1316](https://github.com/Cantera/cantera/pull/1316)) -- Add new `core.h` header file to simplify required includes for high-level Cantera usage ([`demo.cpp`](https://cantera.org/examples/cxx/demo.html), [#1238](https://github.com/Cantera/cantera/pull/1238)) -- Added support for Python 3.11 and dropped support for Python 3.7 ([#1326](https://github.com/Cantera/cantera/pull/1326), [#1406](https://github.com/Cantera/cantera/pull/1406), [#1467](https://github.com/Cantera/cantera/pull/1467)) -- Added support for SUNDIALS versions up to 6.6.0 and dropped support for SUNDIALS 2.x ([#1341](https://github.com/Cantera/cantera/pull/1341), [#1570](https://github.com/Cantera/cantera/pull/1570)) -- Add support for building MATLAB toolbox on Apple Silicon ([#1524](https://github.com/Cantera/cantera/pull/1524)) -- Added SCons option to set `AR` (for example, to use `llvm-ar` instead of `ar`) ([#1424](https://github.com/Cantera/cantera/pull/1424)) - -## Changes to existing capabilities - -- `BulkKinetics` now handles kinetics for any bulk phase, given the appropriate reaction rate parameterizations. As a result, `GasKinetics` is deprecated in favor of `BulkKinetics` ([#1483](https://github.com/Cantera/cantera/pull/1483)) -- Rename C++ phase setter mnemonics to use `D` for density instead of `R` for rho, for example `setState_TR` is deprecated in favor of `setState_TD` ([#1433](https://github.com/Cantera/cantera/pull/1433)) -- Introduce properties for certain reactor features in Python and deprecate the old getter/setter methods. `ReactorNet.initial_time` replaces `ReactorNet.set_initial_time()`, `Wall.velocity` replaces `Wall.set_velocity()`, `Wall.heat_flux` replaces `Wall.set_heat_flux()`, `Wall.expansion_rate` replaces `wall.vdot`, `Wall.heat_rate` replaces `wall.qdot()`, `Valve.time_function` replaces `Valve.set_time_function()`, `MassFlowController.pressure_function` replaces `MassFlowController.set_pressure_function()` and `PressureController.primary` replaces `PressureController.set_master()` ([E#160](https://github.com/Cantera/enhancements/issues/160), [#1515](https://github.com/Cantera/cantera/pull/1515)) -- Improve ability to find non-extinct diffusion flames when using the "auto" solver mode ([E#155](https://github.com/Cantera/enhancements/issues/155), [#1463](https://github.com/Cantera/cantera/pull/1463)) -- Guard against combining Python `Quantity` objects at constant enthalpy and pressure if their pressures aren't equal ([#1517](https://github.com/Cantera/cantera/pull/1517)) -- Allow transport geometry flags in Chemkin input files that are formatted as floating point values ([#1396](https://github.com/Cantera/cantera/pull/1396)) -- Disable irrelevant warnings for extinct diffusion flames ([#1336](https://github.com/Cantera/cantera/pull/1336)) -- Moved Python test suite and examples out of the Python module; they are no longer installed as part of the Cantera Python package. ([E#51](https://github.com/Cantera/enhancements/issues/51), [#1352](https://github.com/Cantera/cantera/pull/1352), [#1354](https://github.com/Cantera/cantera/pull/1354)) -- Drop support for generating `Makefile`s for samples ([#1380](https://github.com/Cantera/cantera/pull/1380)) -- Drop support for compiling in Cygwin ([E#134](https://github.com/Cantera/enhancements/issues/134), [#1367](https://github.com/Cantera/cantera/pull/1367)) -- Migrate to C++17 standard, make use of modern C++ features, and make various style improvements to the C++ code ([E#181](https://github.com/Cantera/enhancements/issues/181), [E#184](https://github.com/Cantera/enhancements/issues/184), [#1246](https://github.com/Cantera/cantera/pull/1246), [#1327](https://github.com/Cantera/cantera/pull/1327), [#1346](https://github.com/Cantera/cantera/pull/1346), [#1438](https://github.com/Cantera/cantera/pull/1438), [#1441](https://github.com/Cantera/cantera/pull/1441), [#1452](https://github.com/Cantera/cantera/pull/1452), [#1507](https://github.com/Cantera/cantera/pull/1507), [#1565](https://github.com/Cantera/cantera/pull/1565), [#1568](https://github.com/Cantera/cantera/pull/1568), [#1571](https://github.com/Cantera/cantera/pull/1571), [#1589](https://github.com/Cantera/cantera/pull/1589)) -- Numerous improvements to the organization and formatting of the Doxygen and Sphinx documentation, in part by using `doxygen-awesome` and the PyData Sphinx theme([E#115](https://github.com/Cantera/enhancements/issues/115), [E#175](https://github.com/Cantera/enhancements/issues/175), [E#179](https://github.com/Cantera/enhancements/issues/179), [#1279](https://github.com/Cantera/cantera/pull/1279), [#1427](https://github.com/Cantera/cantera/pull/1427), [#1518](https://github.com/Cantera/cantera/pull/1518), [#1534](https://github.com/Cantera/cantera/pull/1534), [#1541](https://github.com/Cantera/cantera/pull/1541), [#1543](https://github.com/Cantera/cantera/pull/1543), [#1546](https://github.com/Cantera/cantera/pull/1546), [#1551](https://github.com/Cantera/cantera/pull/1551), [#1557](https://github.com/Cantera/cantera/pull/1557), [#1558](https://github.com/Cantera/cantera/pull/1558), [#1559](https://github.com/Cantera/cantera/pull/1559), [#1561](https://github.com/Cantera/cantera/pull/1561), [#1562](https://github.com/Cantera/cantera/pull/1562), [#1563](https://github.com/Cantera/cantera/pull/1563), [#1567](https://github.com/Cantera/cantera/pull/1567), [#1572](https://github.com/Cantera/cantera/pull/1572), [#1573](https://github.com/Cantera/cantera/pull/1573), [#1582](https://github.com/Cantera/cantera/pull/1582), [#1581](https://github.com/Cantera/cantera/pull/1581), [#1584](https://github.com/Cantera/cantera/pull/1584), [#1590](https://github.com/Cantera/cantera/pull/1590)) -- Various improvements to the SCons build system ([#1268](https://github.com/Cantera/cantera/pull/1268), [#1307](https://github.com/Cantera/cantera/pull/1307), [#1351](https://github.com/Cantera/cantera/pull/1351), [#1360](https://github.com/Cantera/cantera/pull/1360), [#1404](https://github.com/Cantera/cantera/pull/1404), [#1470](https://github.com/Cantera/cantera/pull/1470), [#1472](https://github.com/Cantera/cantera/pull/1472), [#1509](https://github.com/Cantera/cantera/pull/1509), [#1542](https://github.com/Cantera/cantera/pull/1542)) -- Updates to simplify the special behavior that implements different 1D flame types and boundary conditions ([E#165](https://github.com/Cantera/enhancements/issues/165), [E#171](https://github.com/Cantera/enhancements/issues/171), [#1477](https://github.com/Cantera/cantera/pull/1477), [#1514](https://github.com/Cantera/cantera/pull/1514), [#1523](https://github.com/Cantera/cantera/pull/1523), [#1531](https://github.com/Cantera/cantera/pull/1531), [#1555](https://github.com/Cantera/cantera/pull/1555)) -- Make use of C++ `Solution` objects in `Domain1D` and related classes ([#1345](https://github.com/Cantera/cantera/pull/1345), [#1384](https://github.com/Cantera/cantera/pull/1384), [#1444](https://github.com/Cantera/cantera/pull/1444), [#1594](https://github.com/Cantera/cantera/pull/1594), [#1598](https://github.com/Cantera/cantera/pull/1598)) -- Improved error handling for clib `thermo_setDensity` and `thermo_setMolarDensity` methods ([#1413](https://github.com/Cantera/cantera/pull/1413)) -- Speed up Python module import by deferring imports of optional dependencies ([#1428](https://github.com/Cantera/cantera/pull/1428)) -- Link Python `list_data_files` to C++ `getDataDirectories` ([#1358](https://github.com/Cantera/cantera/pull/1358)) -- Remove features deprecated in Cantera 2.6. Principally, this includes legacy reaction rate types ([#1292](https://github.com/Cantera/cantera/pull/1292)) and the CTI/XML input formats ([#1291](https://github.com/Cantera/cantera/pull/1291)) -- Deprecate remaining specializations of `Reaction` class and obsolete methods that were used by legacy reaction rate evaluators ([E#149](https://github.com/Cantera/enhancements/issues/149), [#1295](https://github.com/Cantera/cantera/pull/1295), [#1333](https://github.com/Cantera/cantera/pull/1333)) -- Deprecate other untested, unused and/or obsolete code ([C++ Deprecations](https://cantera.org/documentation/docs-3.0/doxygen/html/da/d58/deprecated.html), [#1455](https://github.com/Cantera/cantera/pull/1455), [#1504](https://github.com/Cantera/cantera/pull/1504)) -- Improve deprecation warnings issued from Python to include the name of the deprecated method and to show the line where that function is called from ([#1519](https://github.com/Cantera/cantera/pull/1519)) - -## Bugs fixed - -- Fixed thermodynamic consistency issues with `SurfPhase` and `RedlichKisterVPSSTP` ([#1449](https://github.com/Cantera/cantera/pull/1449)) -- Fixed thermodynamic consistency errors in IAPWS water equation of state ([#1394](https://github.com/Cantera/cantera/pull/1394)) -- Fixed thermodynamic consistency issues in `IdealSolidSolnPhase` and `BinarySolutionTabulatedThermo` ([#1442](https://github.com/Cantera/cantera/pull/1442)) -- Fix calculation of electron enthalpy contribution in `PlasmaPhase` ([#1323](https://github.com/Cantera/cantera/pull/1323)) -- Fix setting reference pressure for a phase by setting the reference pressure of the individual species ([#1503](https://github.com/Cantera/cantera/pull/1503)) -- Fix issues with "volume" and compressibility of `SurfPhase` ([#1350](https://github.com/Cantera/cantera/pull/1350)) -- Handle factorization errors in equilibrium initial estimator ([#1479](https://github.com/Cantera/cantera/pull/1479)) -- Make helpful errors for invalid reactions work more consistently ([#1330](https://github.com/Cantera/cantera/pull/1330), [#1356](https://github.com/Cantera/cantera/pull/1356)) -- Fix serialization of phases with reactions from multiple YAML sections ([#1552](https://github.com/Cantera/cantera/pull/1552)) -- Fix loading serialized mechanisms where reactions contain undeclared third bodies ([#1588](https://github.com/Cantera/cantera/pull/1588)) -- Fix cases where three-body reactions were not being automatically detected ([#1338](https://github.com/Cantera/cantera/pull/1338)) -- Fix possible segfaults when using Python `CustomRate` ([#1293](https://github.com/Cantera/cantera/pull/1293)) -- Partial fix for PLOG validation at low temperatures ([#1553](https://github.com/Cantera/cantera/pull/1553)) -- Fix default `atol` used in `ReactorNet.advance_to_steady_state` ([#1305](https://github.com/Cantera/cantera/pull/1305)) -- Fix reading arrays containing subnormal floating point values ([#1545](https://github.com/Cantera/cantera/pull/1545)) -- Fix adding Python `Quantity` objects when using molar basis ([#1517](https://github.com/Cantera/cantera/pull/1517)) -- Add missing array properties to `SolutionArray` and `FlameBase` ([#1342](https://github.com/Cantera/cantera/pull/1342)) -- Fix [`surf_pfr_chain.py`](https://cantera.org/examples/python/reactors/surf_pfr_chain.py.html) example to avoid misleading use of perturbed `Solution` objects ([#1304](https://github.com/Cantera/cantera/pull/1304)) -- Fix Matlab samples to resolve issues from transition to YAML input files ([#1414](https://github.com/Cantera/cantera/pull/1414)) -- Fix numerous build issues for certain configurations and platforms ([#1272](https://github.com/Cantera/cantera/pull/1272), [#1362](https://github.com/Cantera/cantera/pull/1362), [#1364](https://github.com/Cantera/cantera/pull/1364), [#1366](https://github.com/Cantera/cantera/pull/1366), [#1378](https://github.com/Cantera/cantera/pull/1378), [#1381](https://github.com/Cantera/cantera/pull/1381), [#1390](https://github.com/Cantera/cantera/pull/1390), [#1434](https://github.com/Cantera/cantera/pull/1434), [#1437](https://github.com/Cantera/cantera/pull/1437), [#1505](https://github.com/Cantera/cantera/pull/1505), [#1511](https://github.com/Cantera/cantera/pull/1511), [#1538](https://github.com/Cantera/cantera/pull/1538), [#1544](https://github.com/Cantera/cantera/pull/1544), [#1574](https://github.com/Cantera/cantera/pull/1574), [#1591](https://github.com/Cantera/cantera/pull/1591)) -- Various documentation updates ([#1276](https://github.com/Cantera/cantera/pull/1276), [#1296](https://github.com/Cantera/cantera/pull/1296), [#1328](https://github.com/Cantera/cantera/pull/1328), [#1335](https://github.com/Cantera/cantera/pull/1335)) - - -## Contributors - -This release was made possible by the following contributors: [@anthony-walker](https://github.com/anthony-walker), [@arghdos](https://github.com/arghdos), [@band-a-prend](https://github.com/band-a-prend), [@BangShiuh](https://github.com/BangShiuh), [@bryanwweber](https://github.com/bryanwweber), [@burkenyo](https://github.com/burkenyo), [@c-randall](https://github.com/c-randall), [@cdeil](https://github.com/cdeil), [@chinahg](https://github.com/chinahg), [@corykinney](https://github.com/corykinney), [@decaluwe](https://github.com/decaluwe), [@g3bk47](https://github.com/g3bk47), [@gkogekar](https://github.com/gkogekar), [@hallaali](https://github.com/hallaali), [@ischoegl](https://github.com/ischoegl), [@jongyoonbae](https://github.com/jongyoonbae), [@kyleniemeyer](https://github.com/kyleniemeyer), [@mefuller](https://github.com/mefuller), [@rwest](https://github.com/rwest), [@speth](https://github.com/speth), [@ssun30](https://github.com/ssun30), [@tsikes](https://github.com/tsikes), [@yeanment](https://github.com/yeanment), [@yurivict](https://github.com/yurivict) diff --git a/pages/examples/index.rst b/pages/examples/index.rst deleted file mode 100644 index a772466c2..000000000 --- a/pages/examples/index.rst +++ /dev/null @@ -1,115 +0,0 @@ -.. title: Examples Index -.. slug: index -.. description: Index of Examples - -.. container:: jumbotron - - .. raw:: html - - <h1 class="display-4">Cantera Examples</h1> - - .. class:: lead - - Cantera includes example scripts for a number of applications. Depending on which interface - you're using, select one of the categories below. - - -.. container:: container - - .. row:: - - .. container:: col-12 - - .. container:: card-deck - - .. container:: card - - .. container:: - :tagname: a - :attributes: href="python/index.html" - title="Python Examples" - - .. container:: card-header section-card - - Python Examples - - .. container:: card-body - - .. container:: card-text - - Examples of using the Python interface - - .. container:: card - - .. container:: - :tagname: a - :attributes: href="matlab/index.html" - title="Matlab Examples" - - .. container:: card-header section-card - - Matlab Examples - - .. container:: card-body - - .. container:: card-text - - Examples of using the Matlab interface - - .. container:: card - - .. container:: - :tagname: a - :attributes: href="jupyter/index.html" - title="Jupyter Notebook Examples" - - .. container:: card-header section-card - - Jupyter Notebook Examples - - .. container:: card-body - - .. container:: card-text - - Examples of using the Jupyter Notebook and the Python interface. - - .. row:: - - .. container:: col-12 - - .. container:: card-deck - - .. container:: card - - .. container:: - :tagname: a - :attributes: href="cxx/index.html" - title="C++ Examples" - - .. container:: card-header section-card - - C++ Examples - - .. container:: card-body - - .. container:: card-text - - Examples of using Cantera directly from C++ applications. - - .. container:: card - - .. container:: - :tagname: a - :attributes: href="fortran/index.html" - title="Fortran Examples" - - .. container:: card-header section-card - - Fortran Examples - - .. container:: card-body - - .. container:: card-text - - Examples of using the Cantera Fortran 90 interface, and of using Cantera from Fortran 77. - diff --git a/pages/governance.rst b/pages/governance.rst deleted file mode 100644 index 3df9c022e..000000000 --- a/pages/governance.rst +++ /dev/null @@ -1,93 +0,0 @@ -.. title: Governance -.. description: Policies and procedures governing the Cantera community -.. slug: governance - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Governance</h1> - - .. class:: lead - - Policies and procedures governing the Cantera community - -Cantera Governance ------------------- - -This document outlines the policies and procedures that manage the Cantera community. - -Code of Conduct -~~~~~~~~~~~~~~~ - -All online and in-person interactions and communications related to Cantera are -governed by the `Cantera Code of Conduct -<https://github.com/Cantera/cantera/blob/main/CODE_OF_CONDUCT.md>`__. This code -of conduct sets expectations for the community to ensure that users and -contributors are able to participate in a respectful and welcoming environment. - -Teams & Roles -~~~~~~~~~~~~~ - -**Steering Committee** - This is the governing body of Cantera, making decisions regarding the structure, - operations, and long-term direction of the project. Each member has one vote for - important project decisions. - -**Committers** - Members of the committers team have commit/push access to the Cantera source code, - and can merge pull requests. - -**Cantera User Group moderators** - Members of the moderators team moderate the User Group, and have power to - enable/disable posting of community members at their discretion. - -Current Steering Committee -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The role of the steering committee is to ensure the long-term health of the -Cantera project. This includes overseeing the development of the Cantera code -and community in a way that most benefits the entire community of users and -contributors. The steering committee can be contacted at `steering@cantera.org -<mailto:steering@cantera.org>`__. The current steering committee (in alphabetical -order) is: - -* Steven DeCaluwe (2018–) -* Connie Gao (2019-) -* \C. Franklin Goldsmith (2018–) -* Kyle Niemeyer (2018–) -* Raymond Speth (2018–) -* Bryan Weber (2018–) -* Richard West (2018–) - -The Steering Committee should have at least five members. Members serve in two-year -cycles (starting in November 2018), with the ability to reaffirm their membership -at the end of each cycle without a committee vote or leave the committee at -their discretion. Members can also choose to leave the committee at any time. - -Voting -~~~~~~ - -The Steering Committee will vote on the following topics, with passing contingent -on a 2/3 majority. All members should vote, but abstentions are permitted. - -* Modifications of the governance procedures -* Adding/removing steering committee members -* Spending project funds -* Adding/removing people with commit rights to GitHub repositories -* Adding/removing moderators of the User’s Group -* Adding/removing people to private communication channels -* Adding/removing people with rights to post as Cantera on social media -* Establishing sub-committees and roles -* Adding/removing members from the Scientific Advisory Board - -The Steering Committee will maintain a Google Doc that records all votes -(but not discussion). Access to the Google Doc will be limited to members of the -Steering Committee. - - -Acknowledgements -~~~~~~~~~~~~~~~~ - -This document was inspired by the `conda-forge governance guidelines -<https://conda-forge.org/docs/orga/governance.html>`__. diff --git a/pages/index.html b/pages/index.html deleted file mode 100644 index db3072220..000000000 --- a/pages/index.html +++ /dev/null @@ -1,231 +0,0 @@ -<!-- - .. title: Cantera - .. slug: index - .. date: 2018-05-30 11:20:56 UTC-04:00 - .. description: Cantera's Homepage - .. type: text - .. template: home.tmpl ---> - -<section id="what-is-cantera"> - - <!-- <h2 style="margin-bottom: 20px;" class="text-center">What is Cantera?</h2> --> - - <div class="container"> - <div class="row"> - <div class="col-md-12"> - <div class="col-md-10 offset-md-1"> - <p class="jumbotron-text">Cantera is an open-source suite of tools for problems - involving chemical kinetics, thermodynamics, and transport processes.</p> - </div> - </div> - </div> - </div> - - <div class="container"> - <div class="row"> - <div class="col-md-3"> - <h4>Automation</h4> - <p> - Cantera automates the chemical kinetic, thermodynamic, and transport calculations so that the - users can efficiently incorporate detailed chemical thermo-kinetics and transport models into - their calculations. - </p> - </div> - <div class="col-md-3"> - <h4>Object-Oriented</h4> - <p> - Cantera utilizes object-oriented concepts for robust yet flexible phase - models, and algorithms are generalized so that users can explore different phase models with - minimal changes to their overall code. - </p> - </div> - <div class="col-md-3"> - <h4>Multiple Interfaces</h4> - <p> - Cantera can be used from Python and Matlab, or - in applications written in C/C++ and Fortran 90. - </p> - </div> - <div class="col-md-3"> - <h4>Broad Applications</h4> - <p> - Cantera is currently used for applications including combustion, detonations, electrochemical - energy conversion and storage, fuel cells, batteries, aqueous electrolyte solutions, plasmas, and - thin film deposition. - </p> - </div> - </div> - </div> -</section> - -<section id="intro-cards"> - <div class="container"> - <div class="row"> - <div class="card-deck"> - <div class="card"> - <a href="/tutorials/index.html" title="Tutorials"> - <div class="card-header section-card">Tutorials</div> - </a> - <div class="card-body"> - <h5 class="card-title">New? Start here!</h5> - <p class="card-text"> - The tutorials linked below will get you started using Cantera on your own machine. - </p> - <!-- <a href="/install/index.html" class="card-link" title="Installation Instructions">Install</a> --> - <a href="/tutorials/python-tutorial.html" class="card-link" title="Python Tutorial">Python</a> - <a href="/tutorials/matlab-tutorial.html" class="card-link" title="Matlab Tutorial">Matlab</a> - <a href="/tutorials/ck2yaml-tutorial.html" class="card-link" title="CK2YAML Tutorial">Convert Input - Files</a> - </div> - </div> - <div class="card"> - <a href="/examples/index.html" title="Examples"> - <div class="card-header section-card">Examples</div> - </a> - <div class="card-body"> - <h5 class="card-title">What can Cantera do?</h5> - <p class="card-text"> - We have a number of examples demonstrating the use of Cantera in some of our interfaces. - </p> - <a href="/examples/python/index.html" class="card-link" title="Python Examples">Python</a> - <a href="/examples/matlab/index.html" class="card-link" title="Matlab Examples">Matlab</a> - <a href="/examples/jupyter/index.html" class="card-link" title="Jupyter Notebook Examples">Jupyter - Notebook</a> - </div> - </div> - <div class="card"> - <a href="/install/index.html" title="Install"> - <div class="card-header section-card"> - Installing & Compiling - </div> - </a> - <div class="card-body"> - Instructions to install pre-built Cantera binaries or to build Cantera from the source - </div> - </div> - </div> - </div> - </div> - <div class="container"> - <div class="row"> - <div class="card-deck"> - <div class="card"> - <a href="/science/index.html" title="Science"> - <div class="card-header section-card"> - Science - </div> - </a> - <div class="card-body"> - A description of the equations that Cantera solves, including equations of state, energy - and mass conservation, and chemical kinetics. - </div> - </div> - <div class="card"> - <a href="/documentation/index.html" title="Documentation"> - <div class="card-header section-card"> - Documentation - </div> - </a> - <div class="card-body"> - Documentation for the classes and functions that make up Cantera. - </div> - </div> - <div class="card"> - <a href="https://mybinder.org/v2/gh/Cantera/cantera-jupyter/main" rel="nofollow" title="Binder"> - <div class="card-header section-card">Open Binder</div> - </a> - <div class="card-body"> - <h5 class="card-title"> - Try Cantera in your Browser! - </h5> - <p class="card-text"> - The Binder service allows you to try out Cantera in the cloud without installing it on your computer. - You'll see some of our examples and be able to run them yourself! - </p> - <a href="https://mybinder.org/v2/gh/Cantera/cantera-jupyter/main" rel="nofollow" class="card-link"> - <img src="https://mybinder.org/badge_logo.svg" alt="Binder" - data-canonical-src="https://mybinder.org/badge_logo.svg" style="max-width:100%;"> - </a> - </div> - </div> - </div> - </div> - </div> -</section> - -<section id="support-and-numfocus"> - <div class="container"> - <div class="row"> - <div class="col-md-6"> - <h2 class="text-center" style="margin-bottom: 20px;">Connect with Cantera</h2> - <div class="row"> - <div class="col-md-9"> - <p> - The <a href="https://groups.google.com/g/cantera-users">Cantera Users’ Group</a> - on Google Groups is the forum where most Cantera users have their questions asked and - answered. If you need help using Cantera and cannot find an answer in the tutorials or - documentation at Cantera's website, consider joining and asking a question - there. Find more information in our <a href="/community.html#the-cantera-users-group">Community - section</a>. - </p> - </div> - <div class="col-md-3"> - <a href="https://groups.google.com/g/cantera-users" rel="nofollow"> - <img alt="Google Groups" class="align-center" src="/assets/img/Groups_Logo.png" style="width: 100px;"> - </a> - </div> - </div> - <div class="row"> - <div class="col-md-9"> - <p> - Cantera is developed by a team of volunteers, and we're always looking for new team members. - If there is a feature you want added, a bug that needs to be fixed, or even just a typo in the - documentation, changes from the community are always welcome. For more, see the section about - <a href="/community.html#contributing-code" title="Contributing Code">contributing code</a> on - our Community page. - </p> - </div> - <div class="col-md-3"> - <p> - <a href="https://github.com/Cantera/cantera" rel="nofollow"> - <img alt="GitHub" class="align-center" src="/assets/img/Git_Logo.png" style="width: 100px;"> - </a> - </p> - </div> - </div> - </div> - <div class="col-md-6"> - <h2 class="text-center" style="margin-bottom: 20px;">How is Cantera Supported?</h2> - <p> - Cantera is a Sponsored Project of NumFOCUS, a 501(c)(3) nonprofit - charity in the United States. NumFOCUS provides Cantera with fiscal, - legal, and administrative support to help ensure the health and - sustainability of the project. Visit <a href="https://numfocus.org">numfocus.org</a> for more information. - </p> - <p> - Donations to Cantera are managed by NumFOCUS. For donors in the United - States, your gift is tax-deductible to the extent provided by law. As with any donation, you should consult - with your tax adviser about your particular tax situation. - </p> - <p> - If you have found Cantera to be useful to your research or company, - please consider making a - <a href="https://numfocus.org/donate-to-cantera" title="Donate to Cantera" rel="nofollow">donation</a> - to support our efforts. All donations will be used exclusively to fund - the development of Cantera's source code, documentation, or community. - </p> - <a href="https://numfocus.org"> - <img alt="Powered by NumFOCUS" class="align-center" src="/assets/img/SponsoredProject.png" - style="width: 250px;"> - </a> - <div class="text-center"> - <a class="btn btn-primary" rel="nofollow" href="https://numfocus.org/donate-to-cantera" - title="Donate to Cantera"> - Donate to Cantera - </a> - </div> - </div> - </div> - </div> -</section> diff --git a/pages/install/compiling-install.rst b/pages/install/compiling-install.rst deleted file mode 100644 index 506b9ba70..000000000 --- a/pages/install/compiling-install.rst +++ /dev/null @@ -1,80 +0,0 @@ -.. title: Compiling Cantera from Source -.. slug: compiling-install -.. date: 2018-08-23 20:16:00 UTC-04:00 -.. description: Compiling Cantera from Source -.. type: text -.. _sec-compiling: - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Compiling Cantera from Source</h1> - - .. class:: lead - - Compiling Cantera from source code uses the SCons build system and a C/C++ compiler. If - you also want to build the Python, Matlab, or Fortran interfaces, you'll need Cython + - Numpy, Matlab, or a Fortran compiler installed, respectively. Specific instructions to - install these things are platform-dependent, and more detail is provided in the sections - linked below. - -**Quickstart** - -First, make sure you have all of the :ref:`compilation requirements -<sec-compilation-reqs>` installed. - -Then, obtain a copy of the Cantera source code directly from the main version control -repository on GitHub via the command - -.. code-block:: bash - - git clone --recursive https://github.com/Cantera/cantera.git - cd cantera - git checkout 3.0 - -which clones the code into a folder called ``cantera`` and changes into that directory. -At this point, you can run - -.. code-block:: bash - - scons help --options - -to see a list of all of the configuration options, including their defaults. On -\*nix-type systems, the defaults will usually pick up the appropriate compilers and -Python versions. The command - -.. code-block:: bash - - scons build - -will build Cantera using all the default options; additional options can be specified -by - -.. code-block:: bash - - scons build option=value option=value - -Installing Cantera into the default directories is done by - -.. code-block:: bash - - scons install - -which may require super-user permissions if the installation directory is protected. - -**Compiling Cantera from Source: The Detailed Way** - -If you want or need more detail, the following sections go into depth on all of the -options and requirements to build Cantera from source. - -* :ref:`Compilation Requirements <sec-compilation-reqs>` - - * :ref:`Cantera's Dependencies <sec-dependencies>` - -* :ref:`Getting the Source Code <sec-source-code>` -* :ref:`Determine Configuration Options & Compile Cantera <sec-determine-config>` - - * :ref:`Show me all of the configuration options <scons-config>` - -* :ref:`Special Compiling Cases <sec-special-compiling-cases>` diff --git a/pages/install/conda-install.rst b/pages/install/conda-install.rst deleted file mode 100644 index 4302f695e..000000000 --- a/pages/install/conda-install.rst +++ /dev/null @@ -1,323 +0,0 @@ -.. title: Installing Cantera with Conda -.. slug: conda-install -.. date: 2018-08-23 20:16:00 UTC-04:00 -.. description: Installation instructions for Cantera using Conda -.. type: text -.. _sec-install-conda: - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Installing with Conda</h1> - - .. class:: lead - - `Anaconda <https://www.anaconda.com/products/individual#Downloads>`__ and - `Miniconda <https://docs.conda.io/en/latest/miniconda.html>`__ are Python - distributions that include the ``conda`` package manager, which can be used to - install Cantera. - -Installing Cantera using Conda can provide the Cantera :ref:`Python module -<sec-conda-python-interface>` and :ref:`MATLAB toolbox <sec-conda-matlab-interface>`, as -well as libraries for linking to applications written in C++, C, or Fortran 90. There -are some exceptions to the availability of each interface depending on the operating -system and Conda channel used. - -Both the Anaconda and Miniconda distributions are available for Linux, macOS (Intel and -ARM/Apple Silicon), and Windows. On Windows, users should install a 64-bit version of -Anaconda or Miniconda, since the Cantera Conda packages are only available for 64-bit -installations. - -Both Anaconda and Miniconda include the ``conda`` package manager; the difference is -that Anaconda includes a large number of Python packages that are widely used in -scientific applications, while Miniconda is a minimal distribution that only includes -Python and Conda, although all of the packages available in Anaconda can be installed in -Miniconda. For more details on how to use conda, see the `conda -documentation <https://docs.conda.io/projects/conda/en/latest/user-guide/index.html>`__. - -Conda can install a large set of packages by default and it is possible to install -packages such as Cantera that are maintained independently. These additional channels -from which packages may be obtained are specified by adding the ``--channel`` option in -the ``install`` or ``create`` commands. - -For instructions on upgrading an existing conda-based installation of Cantera, see -:ref:`Upgrading from an earlier Cantera version <sec-conda-python-upgrade>`. - -.. _sec-conda-python-interface: - -Python interface -================ - -Cantera's Python interface is available from two channels: - -1. The ``cantera`` channel. This channel should be used if you installed - Python from the default channel in conda. This channel also has pre-release versions - of Cantera for testing. Cantera packages are available in this channel for the - following platforms: - - - Windows (64-bit Intel) - - Linux (64-bit Intel) - - macOS (64-bit Intel and 64-bit ARM (Apple Silicon)) - -2. The ``conda-forge`` channel. This channel should be used if you installed Python from - the ``conda-forge`` channel or if your OS/processor combination is not supported by - the ``cantera`` channel. Cantera packages are available in this channel for the - following platforms: - - - Windows (64-bit Intel) - - Linux (64-bit Intel, 64-bit ARM, and 64-bit PPCLE) - - macOS (64-bit Intel and 64-bit ARM (Apple Silicon)) - -**Option 1: Create a new environment for 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: - -.. code:: shell - - conda create --name ct-env --channel cantera cantera ipython matplotlib jupyter - -This will create an environment with Cantera, IPython, Matplotlib, and all their -dependencies installed. In this case, we want to install Cantera from the -``cantera`` channel, so we add ``--channel cantera`` and to tell Conda to look at the -``cantera`` channel in addition to the default channels. - -If you want to use the ``conda-forge`` channel, replace ``--channel cantera`` with -``--channel conda-forge``. - -To use the scripts and modules installed in the ``ct-env`` environment, including Jupyter, -you must activate it it by running: - -.. code:: shell - - conda activate ct-env - -**Option 2: Create a new environment using an environment file** - -This option is similar to **Option 1** but includes a few other packages that -you may find helpful as you're working with Cantera. Copy and paste the contents -of the file shown below into a file called ``environment.yaml``. Then, save the -the file somewhere and remember that location. - -.. code:: yaml - - name: ct-env - channels: - - cantera # or use cantera/label/dev for alpha/beta packages - - defaults - dependencies: - - python # Cantera supports Python 3.8 and up - - cantera - - ipython # optional (needed for nicer interactive command line) - - jupyter # optional (needed for Jupyter Notebook) - - matplotlib # optional (needed for plots) - - python-graphviz # optional (needed for reaction path diagrams) - - pandas # optional (needed for pandas interface) - -From the command line (or the -Anaconda Prompt on Windows), change directory into the folder where you saved -``environment.yaml``: - -.. code:: shell - - cd folder/where/you/saved - -and then run: - -.. code:: shell - - conda env create -f environment.yaml - -This will create an environment called ``ct-env``. Once you've done that, you -need to activate the environment before using any scripts or modules that you -just installed: - -.. code:: shell - - conda activate ct-env - -**Option 3: Install the development version of Cantera** - -To install a recent development snapshot (that is, an alpha or beta version) of -Cantera, use the ``cantera/label/dev`` channel. Assuming you have an environment -named ``ct-dev``, you can type: - -.. code:: shell - - conda activate ct-dev - conda install --channel cantera/label/dev cantera - -If you later want to revert back to the stable version in that environment, first -remove and then reinstall Cantera: - -.. code:: shell - - conda activate ct-dev - conda remove cantera - conda install --channel cantera cantera - -Alternatively, you can remove the ``ct-dev`` environment and follow Options 1 or 2 -above to create a new environment. - -.. _sec-conda-python-upgrade: - -Upgrading from an earlier Cantera version ------------------------------------------ - -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: - -.. code:: shell - - conda activate ct-dev - conda update --channel cantera cantera - -This assumes you are using Python from the default conda channel. If you installed -Python and Cantera from the ``conda-forge`` channel, you should specify the option -``--channel conda-forge``. - -.. _sec-conda-matlab-interface: - -MATLAB interface -================ - -Cantera's MATLAB interface can be installed from the ``cantera`` channel. In this -example, the command will create a new conda environment named ``ct-env``. From the -command line (or the Anaconda Prompt on Windows), run: - -.. code:: shell - - conda create --name ct-env --channel cantera cantera cantera-matlab - -This will create an environment with Cantera's Python and MATLAB interfaces. Even if you -plan to use Cantera via MATLAB, the Python interface is required to convert input files. -In this case, Cantera must be installed from the ``cantera`` channel, so we add -``--channel cantera`` and to tell Conda to look at the ``cantera`` channel in addition -to the default channels. - -To install the a development version of Cantera, specify ``cantera/label/dev`` as the -channel. - -Upgrading from an earlier Cantera version ------------------------------------------ - -If you already have the Cantera MATLAB interface installed in a conda environment -(named, for example, ``ct-env``), you can upgrade it to the latest version available -by running the commands: - -.. code:: shell - - conda activate ct-env - conda update --channel cantera cantera cantera-matlab - -.. _sec-conda-development-interface: - -Development (C++ & Fortran 90) Interface -======================================== - -The Cantera development interface provides header files and libraries needed to compile -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. - -In the following example, Cantera's development interface is installed from the -``cantera/label/dev`` channel. From the command line (or the Anaconda Prompt on -Windows), create a new conda environment named ``ct-dev`` using: - -.. code:: shell - - conda create --name ct-dev --channel cantera/label/dev libcantera-devel - -This will create an environment with Cantera's development interface. In this case, -the addition of ``--channel cantera/label/dev`` ensures that the package is pulled -from the most recent available Cantera version. Note that ``label/dev`` refers to the -experimental development *channel* of Cantera, and not the development *interface*. - -C++ header and libraries are installed within the ``ct-dev`` environment folder, which -itself depends on the type of ``conda`` installation, and is abbreviated as -``path/to/conda/envs`` below. Within the ``ct-dev`` folder, locations follow ``conda`` -recommendations for a given operating system. - -Linux and macOS Systems ------------------------ - -Installation folders are: - -.. code:: shell - - library files path/to/conda/envs/ct-dev/lib - pkg-config path/to/conda/envs/ct-dev/lib/pkgconfig - C++ headers path/to/conda/envs/ct-dev/include - Fortran module files path/to/conda/envs/ct-dev/include/cantera - samples path/to/conda/envs/ct-dev/share/cantera/samples - data files path/to/conda/envs/ct-dev/share/cantera/data - -In addition to ``libcantera-devel``, installation of additional packages is recommended: - -.. code:: shell - - $ conda activate ct-dev - $ conda install cmake scons pkg-config - -C++ programs can be compiled according to instructions outlined in the -:ref:`C++ Guide <sec-compiling-cplusplus>`. Sample folders for C, C++ and Fortran include -preconfigured instruction files to facilitate compilation using the build tools -``SCons`` and ``CMake``, for example: - -.. code:: shell - - $ cd /path/to/conda/envs/ct-dev/share/cantera/samples/cxx/demo - $ scons # uses SConstruct; or - $ cmake . && cmake --build . # uses CMakeLists.txt - -In addition, individual C++ Cantera sample programs can also be compiled using the -``pkg-config`` build system: - -.. code:: shell - - $ g++ demo.cpp -o demo $(pkg-config --cflags --libs cantera) - -In all cases, the build process yields the executable ``demo``, which is run as: - -.. code:: shell - - $ ./demo - -Windows Systems ---------------- - -Installation folders are: - -.. code:: shell - - library files path\to\conda\envs\ct-dev\Library\lib - C++ headers path\to\conda\envs\ct-dev\Library\include - samples path\to\conda\envs\ct-dev\share\cantera\samples - data files path\to\conda\envs\ct-dev\share\cantera\data - -C++ programs can be compiled according to instructions outlined in the -:ref:`C++ Guide <sec-compiling-cplusplus>`. Sample folders for C and C++ programs include -preconfigured instruction files to facilitate compilation using the build tools -``SCons`` and ``CMake``, for example: - -.. code:: shell - - $ cd path\to\conda\envs\ct-dev\share\cantera\samples\cxx\demo - $ scons # uses SConstruct; or - $ cmake . && cmake --build . --config Release # uses CMakeLists.txt - -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 -(named, for example, ``ct-dev``), you can upgrade it to the latest version available -by running the commands: - -.. code:: shell - - conda activate ct-dev - conda update --channel cantera/label/dev libcantera-devel diff --git a/pages/install/fedora-rhel-install.rst b/pages/install/fedora-rhel-install.rst deleted file mode 100644 index 8e104e54c..000000000 --- a/pages/install/fedora-rhel-install.rst +++ /dev/null @@ -1,68 +0,0 @@ -.. title: Installing Cantera on Fedora -.. date: 2022-01-23 16:16:00 UTC+02:00 -.. description: Installation instructions for Cantera on Fedora -.. type: text -.. _sec-install-fedora-rhel: - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Installing on Fedora</h1> - - .. class:: lead - - RPM packages are provided for supported versions of Fedora Linux. - Stable builds are available in the official repositories and development builds are in a - Community Projects (COPR) repository. The Matlab interface is not available from this archive; - to install the Matlab interface on Fedora, you must :ref:`compile the source code <sec-compiling>`. - -As of Cantera 2.6.0, packages are available for currently supported releases of Fedora Linux -and Fedora Rawhide as well as Enterprise Linux 8. - -The available packages are: - -- ``python3-cantera`` - The Cantera Python module for Python 3. - -- ``cantera-devel`` - Shared object libraries and header files for compiling your own C++ and - Fortran 90 programs that use Cantera. - -- ``cantera-common`` - Cantera data files and example programs. - -- ``cantera-static`` - Static libraries for C++ and Fortran 90 development. - -Cantera is available in the official repositories for Fedora - no configuration -changes are required. - -On Enterprise Linux, if not already enabled, add the "Extra Packages for Enterprise -Linux" (EPEL) repository: - -.. code-block:: bash - - $ dnf install epel-release - -To install all of the Cantera packages: - -.. code-block:: bash - - $ dnf install python3-cantera cantera-devel - -or install whichever subset you need by adjusting the above command. The ``cantera-common`` -package is installed as a dependency if any other Cantera packages are selected. - -If you plan on using Cantera from Python, you may also want to install IPython -(an advanced interactive Python interpreter) and Matplotlib (a plotting -library). Matplotlib is required to run some of the Python examples. These packages -can be installed with: - -.. code-block:: bash - - $ dnf install python3-matplotlib python3-ipython - -To access the development builds of Cantera 3+, enable the COPR, then install as described -above: - -.. code-block:: bash - - $ dnf copr enable fuller/cantera-test - diff --git a/pages/install/freebsd-install.rst b/pages/install/freebsd-install.rst deleted file mode 100644 index 01f9a98d3..000000000 --- a/pages/install/freebsd-install.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. title: Installing Cantera on FreeBSD -.. date: 2021-12-17 14:16:00 UTC-05:00 -.. description: Installation instructions for Cantera on FreeBSD -.. type: text -.. _sec-install-freebsd: - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Installing on FreeBSD</h1> - - .. class:: lead - - A community-maintained FreeBSD port ``science/cantera`` and package are available. - This port provides the Octave interface when the OCTAVE option is turned on. - Note that the Matlab interface is not available from this port; to install the - Matlab interface on FreeBSD, you must :ref:`compile Cantera's source code - <sec-compiling>`. - -Further information about the Cantera package can be found on `FreeBSD.org -<https://www.freebsd.org/cgi/ports.cgi?query=cantera&stype=all>`__ and `FreshPorts.org -<https://www.freshports.org/science/cantera/>`__. The package can be installed via - -.. code:: shell - - pkg install cantera diff --git a/pages/install/gentoo-install.rst b/pages/install/gentoo-install.rst deleted file mode 100644 index a7b1f1067..000000000 --- a/pages/install/gentoo-install.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. title: Installing Cantera on Gentoo -.. slug: gentoo-install -.. date: 2019-06-26 20:00:00 UTC-04:00 -.. description: Installation instructions for Cantera on Gentoo -.. type: text -.. _sec-install-gentoo: - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Installing on Gentoo</h1> - - .. class:: lead - - Gentoo `sci-libs/cantera <https://packages.gentoo.org/packages/sci-libs/cantera>`__ package is provided using a main portage tree. - Additionally the `app-doc/cantera-docs <https://packages.gentoo.org/packages/app-doc/cantera-docs>`__ package - is provided for offline Documentation API reference for Cantera package libraries. - Note that the Matlab interface is not available from this package; to install the - Matlab interface on Gentoo, you must :ref:`compile the source code <sec-compiling>`. - -The following interfaces and tools are installed by default: - -- C++ Libraries and header files for compiling your own programs that use Cantera. - -- `YAML tools <../tutorials/ck2yaml-tutorial.html>`__. - -- Python module for Python 3 (``python`` USE flag with appropriate ``PYTHON_SINGLE_TARGET``, optional). - -The following additional interface is available: - -- Fortran Library and module files for compiling your own programs that use Cantera (``fortran`` USE flag, optional) - -More information about ``USE flags`` can be found in the `Gentoo Handbook <https://wiki.gentoo.org/wiki/Handbook:Parts/Working/USE>`__. -To know about per-package control of ``USE flags`` please refer to the `/etc/portage/package.use <https://wiki.gentoo.org/wiki//etc/portage/package.use>`__ article. - -To install ``sci-libs/cantera`` and ``app-doc/cantera-docs`` packages: - -.. code-block:: bash - - emerge --ask cantera cantera-docs - -Most likely the latest versions of these packages and/or some of their dependencies still have unstable status in the Gentoo portage tree -and then you have to ``unmask`` (allow to install within stable system) them preliminarily using `/etc/portage/package.accept_keywords <https://wiki.gentoo.org/wiki//etc/portage/package.accept_keywords>`__. - -If ``/etc/portage/package.accept_keywords`` is present in your system as file then (for 64-bit architecture) you could unmask ``sci-libs/cantera`` package by running command (as root) - -.. code-block:: bash - - echo "sci-libs/cantera ~amd64" >> /etc/portage/package.accept_keywords - -Otherwise if ``/etc/portage/package.accept_keywords`` is present in your system as directory then run command (as root) - -.. code-block:: bash - - echo "sci-libs/cantera ~amd64" >> /etc/portage/package.accept_keywords/cantera - -If you plan on using Cantera from Python, you may also want to install IPython -(`dev-python/ipython <https://packages.gentoo.org/packages/dev-python/ipython>`__, an advanced interactive Python interpreter) -and Matplotlib (`dev-python/matplotlib <https://packages.gentoo.org/packages/dev-python/matplotlib>`__, a plotting -library). Matplotlib is required to run some of the Python examples. These packages can be installed with: - -.. code-block:: bash - - emerge --ask ipython matplotlib diff --git a/pages/install/install.rst b/pages/install/install.rst deleted file mode 100644 index 98daec7db..000000000 --- a/pages/install/install.rst +++ /dev/null @@ -1,78 +0,0 @@ -.. title: Installing Cantera -.. slug: index -.. date: 2019-06-26 20:00:00 UTC-04:00 -.. description: Installation instructions for Cantera -.. type: text - -.. _sec-install: - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Installing Cantera</h1> - - .. class:: lead - - The following instructions detail how to install the different Cantera interfaces - on a variety of platforms. We highly recommend that all new users install the - Python interface via :ref:`Conda <sec-install-conda>`. - -Installing the Cantera Python Interface -======================================= - -- If you don't already have Python installed (or already use Conda), the easiest way to - install the Cantera Python interface on all operating systems is by - using :ref:`Conda <sec-install-conda>`. - -- If you already have a different Python installation, Cantera can be installed using - :ref:`Pip <sec-install-pip>`. - -- Ubuntu users can install the ``cantera-python3`` package from the - :ref:`Cantera PPA <sec-install-ubuntu>`. - -- Fedora / Enterprise Linux users can install ``python3-cantera`` using - :ref:`dnf <sec-install-fedora-rhel>`. - -- OpenSUSE users can install packages using - :ref:`zypper <sec-install-opensuse>`. - -- Gentoo users can install using :ref:`emerge <sec-install-gentoo>`. - -- FreeBSD users can install using :ref:`pkg <sec-install-freebsd>`. - -- If you want to use the current development version, or add features of your own, you - should :ref:`compile Cantera from source <sec-compiling>`. - -Installing the Cantera Matlab Toolbox -===================================== -- The Cantera Matlab toolbox can be installed on all operating systems using - :ref:`Conda <sec-conda-matlab-interface>`. - -- Windows users can use :ref:`MSI installer packages <sec-install-windows>`. - -- macOS users can also install using a :ref:`.pkg installer <sec-install-macos>`. - -- If you want to use the current development version, or add features of your own, you - should :ref:`compile Cantera from source <sec-compiling>`. - -Installing the Cantera C++ Interface & Fortran 90 Module -======================================================== -- The Cantera development interface can be installed on all operating systems using - :ref:`Conda <sec-conda-development-interface>`. - -- Ubuntu users can install the ``cantera-dev`` package from the - :ref:`Cantera PPA <sec-install-ubuntu>`. - -- Fedora / Enterprise Linux users can install packages using - :ref:`yum/dnf <sec-install-fedora-rhel>`. - -- OpenSUSE users can install packages using - :ref:`zypper <sec-install-opensuse>`. - -- Gentoo users can install using :ref:`emerge <sec-install-gentoo>`. - -- FreeBSD users can install using :ref:`pkg <sec-install-freebsd>`. - -- Users of other Linux distributions should - :ref:`compile Cantera from source <sec-compiling>`. diff --git a/pages/install/macos-install.rst b/pages/install/macos-install.rst deleted file mode 100644 index 39c54cf38..000000000 --- a/pages/install/macos-install.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. title: Installing Cantera on macOS -.. slug: macos-install -.. date: 2018-08-23 20:16:00 UTC-04:00 -.. description: Installation instructions for Cantera on macOS/Mac OS X -.. type: text -.. _sec-install-macos: - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Installing on macOS - - .. class:: lead - - The Cantera Matlab toolbox can be installed using a macOS-specific installer. The - toolbox requires macOS version 10.15 (Catalina) or higher and a copy of Matlab - built for Intel processors (which will run under Rosetta 2 on ARM-based - processors). - -To install the Cantera Python package, see the :ref:`pip <sec-install-pip>` or -:ref:`conda <sec-install-conda>` instructions. The Python package is required if: - -- You need to convert legacy input files to YAML -- You need to convert Chemkin-format input files to YAML - -**Download and run the Matlab Interface Installer** - -Download the Matlab Interface Installer package from GitHub: -https://github.com/Cantera/cantera/releases/ - -When the file has downloaded, find it in Finder, hold Control and click the file. Choose -"Open" from the resulting menu, and select "Open" in the security dialog that appears. -Click "Continue" to proceed in the installer (noting that the installer may open in the background; -you can find its icon on the Dock), agreeing to the -`Cantera license terms <https://github.com/Cantera/cantera/blob/main/License.txt>`__ -and the terms of the other open source software that we use. - -By default, the installer will add some lines to the file ``$HOME/Documents/MATLAB/startup.m`` -to enable loading the Cantera toolbox when Matlab starts. If you wish to disable this, click -"Customize" and de-select the "Install startup.m script" option. Finally, clicking "Install" -will install the interface to the ``$HOME/Applications/Cantera`` folder. - -**Test the installation** - -Open Matlab and enter the following code: - -.. code-block:: matlab - - gas = Solution('gri30.yaml') - h2o = Solution('liquidvapor.yaml','water') diff --git a/pages/install/opensuse-install.rst b/pages/install/opensuse-install.rst deleted file mode 100644 index 5d96e4f9b..000000000 --- a/pages/install/opensuse-install.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. title: Installing Cantera on openSUSE -.. date: 2022-01-23 16:16:00 UTC+02:00 -.. description: Installation instructions for Cantera on openSUSE -.. type: text -.. _sec-install-opensuse: - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Installing on openSUSE</h1> - - .. class:: lead - - RPM packages are provided for openSUSE Tumbleweed. - Note that the Matlab interface is not available from this archive; - to install the Matlab interface on openSUSE, you must :ref:`compile the source code <sec-compiling>`. - -As of Cantera 2.6.0, packages are available for openSUSE Tumbleweed from a -community repository. - -Installation is as follows: - -.. code-block:: bash - - $ zypper addrepo https://download.opensuse.org/repositories/home:fuller/openSUSE_Tumbleweed/home:fuller.repo - $ zypper refresh - $ zypper install cantera diff --git a/pages/install/pip-install.rst b/pages/install/pip-install.rst deleted file mode 100644 index 462c61abf..000000000 --- a/pages/install/pip-install.rst +++ /dev/null @@ -1,178 +0,0 @@ -.. title: Installing Cantera with Pip -.. slug: pip-install -.. description: Installation instructions for Cantera using Pip -.. type: text -.. _sec-install-pip: - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Installing with Pip</h1> - - .. class:: lead - - `Pip <https://pip.pypa.io/en/stable/>`__ is a package installer for Python that - can be used to install the Cantera Python module from - `PyPI <https://pypi.org/project/Cantera/>`__. - -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. - -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 manager. - -To check that you are able run `pip`, open a terminal / command prompt and run the -following command: - -*Linux / macOS*: - -.. code:: shell - - python3 -m pip --version - -*Windows*: - -.. code:: shell - - py -m pip --version - -If the above command doesn't work, see the instructions at -`packaging.python.org <https://packaging.python.org/en/latest/tutorials/installing-packages/>`__ -for how to get `pip` working with your Python installation. - -Virtual Environments -==================== - -Virtual environments provide a way keeping separate sets of Python packages installed -for different projects, where different environments can have different versions of -packages that might otherwise conflict. To create and activate a virtual environment -named ``ct-env`` to be used with Cantera, run the commands: - -*Linux / macOS*: - -.. code:: shell - - python3 -m venv ct-env - source ct-env/bin/activate - - -*Windows*: - -.. code:: bat - - py -m venv ct-env - ct-env\Scripts\activate - -The second command should be run in the terminal each time you want to use the specified -environment. - -Installing Cantera -================== - -To install the Cantera Python module, first activate your virtual environment, if you're -using one. Then, run the command: - -*Linux / macOS*: - -.. code:: shell - - python3 -m pip install cantera - -*Windows*: - -.. code:: bat - - py -m pip install cantera - -You can test that your installation is working by importing the Cantera module and -creating a ``Solution`` object: - -*Linux / macOS*: - -.. code:: shell - - python3 -c 'import cantera; gas = cantera.Solution("gri30.yaml"); gas()' - -*Windows*: - -.. code:: bat - - py -c "import cantera; gas = cantera.Solution('gri30.yaml'); gas()" - -You should get the following output:: - - gri30: - - temperature 300 K - pressure 1.0133e+05 Pa - density 0.081894 kg/m^3 - mean mol. weight 2.016 kg/kmol - phase of matter gas - - 1 kg 1 kmol - --------------- --------------- - enthalpy 26469 53361 J - internal energy -1.2108e+06 -2.441e+06 J - entropy 64910 1.3086e+05 J/K - Gibbs function -1.9447e+07 -3.9204e+07 J - heat capacity c_p 14311 28851 J/K - heat capacity c_v 10187 20536 J/K - - mass frac. Y mole frac. X chem. pot. / RT - --------------- --------------- --------------- - H2 1 1 -15.717 - [ +52 minor] 0 0 - -Installing a Pre-release ------------------------- - -Sometimes, a pre-release (alpha or beta) version of Cantera may be available to install. -However, ``pip`` defaults to installing the latest stable version. To allow installation -of a pre-release, add the ``--pre`` flag: - -*Linux / macOS*: - -.. code:: shell - - python3 -m pip install --pre cantera - -*Windows*: - -.. code:: bat - - py -m pip install --pre cantera - -You can check the version that was installed by running: - -*Linux / macOS*: - -.. code:: shell - - python3 -c 'import cantera; print(cantera.__version__)' - -*Windows*: - -.. code:: bat - - py -c "import cantera; print(cantera.__version__)" - -Limitations -=========== - -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 is 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 -:ref:`Conda <sec-install-conda>` packages instead. diff --git a/pages/install/ubuntu-install.rst b/pages/install/ubuntu-install.rst deleted file mode 100644 index bd1429cf2..000000000 --- a/pages/install/ubuntu-install.rst +++ /dev/null @@ -1,116 +0,0 @@ -.. title: Installing Cantera on Ubuntu -.. slug: ubuntu-install -.. date: 2018-08-23 20:16:00 UTC-04:00 -.. description: Installation instructions for Cantera on Ubuntu -.. type: text -.. _sec-install-ubuntu: - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Installing on Ubuntu</h1> - - .. class:: lead - - Ubuntu packages are provided for recent versions of Ubuntu using a Personal - Package Archive (PPA). - -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). To -see which Ubuntu releases and Cantera versions are currently supported, visit -https://launchpad.net/~cantera-team/+archive/ubuntu/cantera. - -The available packages are: - -- ``cantera-python3`` - 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 - Fortran 90 applications. - -- ``cantera`` - A metapackage that will install everything except for the development - files. - -Note that the Matlab packages are not available from this archive; to install the -Matlab packages on Ubuntu, you must install it using -:ref:`conda <sec-conda-matlab-interface>` -or :ref:`compile the source code <sec-compiling>`. - -Installing ----------- - -To add the Cantera PPA: - -.. code-block:: bash - - sudo apt install software-properties-common - sudo apt-add-repository ppa:cantera-team/cantera - -To install all of the Cantera packages: - -.. code-block:: bash - - sudo apt install cantera-python3 libcantera-dev - -or install whichever subset you need by adjusting the above command. The ``cantera-common`` -package is installed as a dependency if any other Cantera packages are selected. - -If you plan on using Cantera from Python, you may also want to install IPython -(an advanced interactive Python interpreter) and Matplotlib (a plotting -library). Matplotlib is required to run some of the Python examples. These packages -can be installed with: - -.. code-block:: bash - - sudo apt install python3-pip - pip3 install ipython matplotlib - -Upgrading from an earlier Cantera version ------------------------------------------ - -If you already have Cantera installed from the ``cantera-team`` PPA, you can ensure that -you have the latest available version installed by running: - -.. code-block:: bash - - sudo apt update - sudo apt install cantera-python3 - -If you also have the ``libcantera-dev`` package installed, it should also be included on -the ``apt install`` command line. - -Installing pre-release Cantera versions ---------------------------------------- - -Sometimes, pre-release (alpha or beta) versions of Cantera which represent work toward -the next Cantera release will be available for users who want to use cutting-edge -features or test compatibility with the new version before it is released. To see the -latest Cantera versions available from this PPA, visit -https://launchpad.net/~cantera-team/+archive/ubuntu/cantera-unstable. - -These packages can be installed by additionally enabling the -``cantera-team/cantera-unstable`` PPA and then upgrading Cantera: - -.. code-block:: bash - - sudo apt-add-repository ppa:cantera-team/cantera-unstable - sudo apt install cantera-python3 libcantera-dev - -You should also have the ``cantera-team/cantera`` PPA enabled, since the -``cantera-unstable`` PPA *only* includes development versions. - -If you later want to remove the development version and return to the latest stable -version, run the commands: - -.. code-block:: 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 diff --git a/pages/install/windows-install.rst b/pages/install/windows-install.rst deleted file mode 100644 index a37731586..000000000 --- a/pages/install/windows-install.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. title: Installing Cantera on Windows -.. slug: windows-install -.. date: 2018-08-23 20:16:00 UTC-04:00 -.. description: Installation instructions for Cantera on Windows -.. type: text -.. _sec-install-windows: - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Installing on Windows</h1> - - .. class:: lead - - Windows installers are provided for stable versions of Cantera. These installers - provide the Matlab toolbox and header/library files that can be used to compile - C++ applications. - -To install the Cantera Python package, see the :ref:`pip <sec-install-pip>` or -:ref:`conda <sec-install-conda>` 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 - -**Remove old versions of Cantera** - -- Use The Windows "Add/Remove Programs" interface to remove previous versions of - the `Cantera` package. - -**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. - -**Configure Matlab** - -- Launch Matlab - -- Go to *File->Set Path...* - -- Select *Add with Subfolders* - -- Browse to the folder ``C:\Program Files\Cantera\matlab\toolbox`` - -- Select *Save*, then *Close*. - -**Test the installation** - -- From the Matlab prompt, run: - - .. code-block:: matlab - - gas = Solution('gri30.yaml') - h2o = Solution('liquidvapor.yaml', 'water') diff --git a/pages/science/flames.rst b/pages/science/flames.rst deleted file mode 100644 index f3a019df3..000000000 --- a/pages/science/flames.rst +++ /dev/null @@ -1,258 +0,0 @@ -.. slug: flames -.. title: One-dimensional Flames -.. has_math: true - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">One-Dimensional Flames</h1> - - .. class:: lead - - Cantera includes a set of models for representing steady-state, quasi-one- - dimensional reacting flows. - - These models can be used to simulate a number of common flames, such as: - - - freely-propagating premixed laminar flames - - burner-stabilized premixed flames - - counterflow diffusion flames - - counterflow (strained) premixed flames - - Additional capabilities include simulation of surface reactions, which can be - used to represent processes such as combustion on a catalytic surface or - chemical vapor deposition processes. - - All of these configurations are simulated using a common set of governing - equations within a 1D flow domain, with the differences between the models - being represented by differences in the boundary conditions applied. Here, we - describe the governing equations and the various boundary conditions which can - be applied. - -Stagnation Flow Governing Equations -=================================== - -Cantera models flames that are stabilized in an axisymmetric stagnation flow, -and computes the solution along the stagnation streamline (:math:`r=0`), using a -similarity solution to reduce the three-dimensional governing equations to a -single dimension. - -The governing equations for a steady axisymmetric stagnation flow follow those -derived in Section 7.2 of [Kee2017]_: - -*Continuity*: - -.. math:: - - \frac{\partial\rho u}{\partial z} + 2 \rho V = 0 - -*Radial momentum*: - -.. math:: - - \rho u \frac{\partial V}{\partial z} + \rho V^2 = - - \Lambda - + \frac{\partial}{\partial z}\left(\mu \frac{\partial V}{\partial z}\right) - - -*Energy*: - -.. math:: - - \rho c_p u \frac{\partial T}{\partial z} = - \frac{\partial}{\partial z}\left(\lambda \frac{\partial T}{\partial z}\right) - - \sum_k j_k \frac{\partial h_k}{\partial z} - - \sum_k h_k W_k \dot{\omega}_k - -*Species*: - -.. math:: - - \rho u \frac{\partial Y_k}{\partial z} = - \frac{\partial j_k}{\partial z} - + W_k \dot{\omega}_k - -where :math:`\rho` is the density, :math:`u` is the axial velocity, :math:`v` is -the radial velocity, :math:`V = v/r` is the scaled radial velocity, -:math:`\Lambda` is the pressure eigenvalue (independent of :math:`z`), -:math:`\mu` is the dynamic viscosity, :math:`c_p` is the heat capacity at -constant pressure, :math:`T` is the temperature, :math:`\lambda` is the thermal -conductivity, :math:`Y_k` is the mass fraction of species :math:`k`, :math:`j_k` -is the diffusive mass flux of species :math:`k`, :math:`c_{p,k}` is the specific -heat capacity of species :math:`k`, :math:`h_k` is the enthalpy of species -:math:`k`, :math:`W_k` is the molecular weight of species :math:`k`, and -:math:`\dot{\omega}_k` is the molar production rate of species :math:`k`. - -The tangential velocity :math:`w` has been assumed to be zero. The model is -applicable to both ideal and non-ideal fluids, which follow ideal-gas or real-gas -(Redlich-Kwong and Peng-Robinson) equations of state. The real-gas support for -the flame models has been newly implemented as a part of Cantera 3.0. - -To help in the solution of the discretized problem, it is convenient to write a -differential equation for the scalar :math:`\Lambda`: - -.. math:: - - \frac{d\Lambda}{dz} = 0 - -Diffusive Fluxes ----------------- - -The species diffusive mass fluxes :math:`j_k` are computed according to either a -mixture-averaged or multicomponent formulation. If the mixture-averaged -formulation is used, the calculation performed is: - -.. math:: - - j_k^* = - \rho \frac{W_k}{\overline{W}} D_{km}^\prime \frac{\partial X_k}{\partial z} - - j_k = j_k^* - Y_k \sum_i j_i^* - -where :math:`\overline{W}` is the mean molecular weight of the mixture, :math:`D_{km}^\prime` is the -mixture-averaged diffusion coefficient for species :math:`k`, and :math:`X_k` is the mole fraction -for species :math:`k`. The diffusion coefficients used here are those computed by the method -`GasTransport::getMixDiffCoeffs <{{% ct_docs doxygen/html/d8/d58/classCantera_1_1GasTransport.html#a699001499937e42f790551f01bce4424 %}}>`__. -The correction applied by the second equation ensures that the sum of the mass fluxes is zero, a -condition which is not inherently guaranteed by the mixture-averaged formulation. - -When using the multicomponent formulation, the mass fluxes are computed -according to: - -.. math:: - - j_k = \frac{\rho W_k}{\overline{W}^2} \sum_i W_i D_{ki} \frac{\partial X_i}{\partial z} - - \frac{D_k^T}{T} \frac{\partial T}{\partial z} - -where :math:`D_{ki}` is the multicomponent diffusion coefficient and -:math:`D_k^T` is the Soret diffusion coefficient (used only if calculation of -this term is specifically enabled). - -Boundary Conditions -=================== - -Inlet boundary --------------- - -For a boundary located at a point :math:`z_0` where there is an inflow, values -are supplied for the temperature :math:`T_0`, the species mass fractions -:math:`Y_{k,0}` the scaled radial velocity :math:`V_0`, and the mass flow rate -:math:`\dot{m}_0` (except in the case of the freely-propagating flame). - -The following equations are solved at the point :math:`z = z_0`: - -.. math:: - - T(z_0) = T_0 - - V(z_0) = V_0 - - \dot{m}_0 Y_{k,0} - j_k(z_0) - \rho(z_0) u(z_0) Y_k(z_0) = 0 - -If the mass flow rate is specified, we also solve: - -.. math:: - - \rho(z_0) u(z_0) = \dot{m}_0 - -Otherwise, we solve: - -.. math:: - - \Lambda(z_0) = 0 - -Outlet boundary ---------------- - -For a boundary located at a point :math:`z_0` where there is an outflow, we -solve: - -.. math:: - - \Lambda(z_0) = 0 - - \left.\frac{\partial T}{\partial z}\right|_{z_0} = 0 - - \left.\frac{\partial Y_k}{\partial z}\right|_{z_0} = 0 - - V(z_0) = 0 - - -Symmetry boundary ------------------ - -For a symmetry boundary located at a point :math:`z_0`, we solve: - -.. math:: - - \rho(z_0) u(z_0) = 0 - - \left.\frac{\partial V}{\partial z}\right|_{z_0} = 0 - - \left.\frac{\partial T}{\partial z}\right|_{z_0} = 0 - - j_k(z_0) = 0 - -Reacting surface ----------------- - -For a surface boundary located at a point :math:`z_0` on which reactions may -occur, the temperature :math:`T_0` is specified. We solve: - -.. math:: - - \rho(z_0) u(z_0) = 0 - - V(z_0) = 0 - - T(z_0) = T_0 - - j_k(z_0) + \dot{s}_k W_k = 0 - -where :math:`\dot{s}_k` is the molar production rate of the gas-phase species -:math:`k` on the surface. In addition, the surface coverages :math:`\theta_i` -for each surface species :math:`i` are computed such that :math:`\dot{s}_i = 0`. - -The Drift-Diffusion Model -========================= - -To account for the transport of charged species in a flame, class `IonFlow <{{% ct_docs -doxygen/html/d4/db9/classCantera_1_1IonFlow.html %}}>`__ adds the drift term to the -diffusive fluxes of the mixture-average formulation according to [Ped1993]_, - -.. math:: - - j_k^* = \rho \frac{W_k}{\overline{W}} D_{km}^\prime \frac{\partial X_k}{\partial z} + - s_k \mu_k E Y_k, - -where :math:`s_k` is the sign of charge (1,-1, and 0 respectively for positive, negative, -and neutral charge), :math:`\mu_k` is the mobility, and :math:`E` is the electric field. -The diffusion coefficients and mobilities of charged species can be more accurately -calculated by `IonGasTransport::getMixDiffCoeffs <{{% ct_docs doxygen/html/d4/d65/classCantera_1_1IonGasTransport.html#a431711980258846b25827541b65c2728 %}}>`__ -and `IonGasTransport::getMobilities <{{% ct_docs doxygen/html/d4/d65/classCantera_1_1IonGasTransport.html#a702cbb6f244cfb9f448ac0630def9893 %}}>`__. -The following correction is applied instead to preserve the correct fluxes of charged species: - -.. math:: - - j_k = j_k^* - \frac {1 - |s_k|} {1 - \sum_i |s_i| Y_i} Y_k \sum_i j_i^*. - -In addition, Gauss's law is solved simultaneously with the species and energy equations, - -.. math:: - - \frac{\partial E}{\partial z} = \frac{e}{\epsilon_0}\sum_k Z_k n_k , - - n_k = N_a \rho Y_k / W_k, - - E|_{z=0} = 0, - -where :math:`Z_k` is the charge number, :math:`n_k` is the number density, -and :math:`N_a` is the Avogadro number. - -.. rubric:: References - -.. [Kee2017] R. J. Kee, M. E. Coltrin, P. Glarborg, and H. Zhu. *Chemically Reacting Flow: - Theory and Practice*. 2nd Ed. John Wiley and Sons, 2017. - -.. [Ped1993] T. Pederson and R. C. Brown. Simulation of electric field effects in premixed - methane flames. *Combustion and Flames*, 94.4:433-448, 1993. - DOI: https://doi.org/10.1016/0010-2180(93)90125-M. diff --git a/pages/science/index.rst b/pages/science/index.rst deleted file mode 100644 index e3c480ea3..000000000 --- a/pages/science/index.rst +++ /dev/null @@ -1,144 +0,0 @@ -.. title: Cantera Science -.. slug: index -.. date: 2018-05-30 11:20:56 UTC-04:00 -.. description: Cantera Science page -.. type: text - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Science & Theory</h1> - - .. class:: lead - - While Cantera's documentation gives insight into the various classes and functions that - constitute Cantera's capabilities, software documentation does not always provide a great - format for diving into scientific theory. This section describes the equations and models - Cantera uses to represent the real world. - -.. raw:: html - - <h2>Chemical Kinetic Theory</h2> - -These sections describe some of the fundamental scientific theory underpinning the ways that Cantera models phases -of matter. This involves calculations for thermodynamic and transport properties and chemical -reaction rates. The above information gives some insight into the basic constitutive models -available in Cantera: capabilities for calculating the basic thermodynamic, chemical kinetic, and transport properties of phases of matter, which can be -extended to model a wide range of science and technology applications. - -.. container:: container - :tagname: section - - .. container:: card-deck - - .. container:: card - - .. container:: - :tagname: a - :attributes: href=thermodynamics.html - title=Thermodynamics - - .. container:: card-header section-card - :tagname: div - - Thermodynamics - - .. container:: card-body - - .. container:: card-text - - The theory behind how Cantera calculates species and phase thermodynamic properties. - - .. container:: card - - .. container:: - :tagname: a - :attributes: href=kinetics.html - title=Kinetics - - .. container:: card-header section-card - :tagname: div - - Kinetics and Reaction Rates - - .. container:: card-body - - .. container:: card-text - - The models and equations that Cantera uses to calculate chemical reaction rates. - - .. container:: card - - .. container:: - :tagname: a - :attributes: href=transport.html - title=Transport - - .. container:: card-header section-card - :tagname: div - - Transport - - .. container:: card-body - - .. container:: card-text - - The models that Cantera uses to calculate transport properties and rates. - -.. raw:: html - - <h2>Cantera Reactor and Flame Models</h2> - -Cantera comes with a number of zero- and one-dimensional models: reactor and flame models for a -number of well-defined and commonly encountered phenomena. Below we give an overview of the theory -and and function of these models. You can also see the `Cantera examples </examples/index.html>`__ -to see how these models might be used. - -.. container:: container - :tagname: section - - .. container:: card-deck - - .. container:: card - - .. container:: - :tagname: a - :attributes: href=reactors/reactors.html - title=Reactors - - .. container:: card-header section-card - - Reactors - - .. container:: card-body - - .. container:: card-text - - Cantera provides a range of generalized zero-dimensional models that can be given a - range of initial and boundary conditions and can also be linked to form reactor - networks. - - .. container:: card - - .. container:: - :tagname: a - :attributes: href=flames.html - title=Flames - - .. container:: card-header section-card - - Flames - - .. container:: card-body - - .. container:: card-text - - Cantera includes a set of models for representing steady-state, quasi-one-dimensional - reacting flows, which can be used to simulate a number of common flames. - - -Note that this information is simply an overview. For a thorough, comprehensive description of -chemical kinetic theory and the associated governing equations for a variety of systems, a very -useful reference is R. J. Kee, M. E. Coltrin, P. Glarborg, and H. Zhu. *Chemically Reacting Flow: -Theory and Practice*. 2nd Ed. John Wiley and Sons, 2017. diff --git a/pages/science/kinetics.rst b/pages/science/kinetics.rst deleted file mode 100644 index ded15f58c..000000000 --- a/pages/science/kinetics.rst +++ /dev/null @@ -1,544 +0,0 @@ -.. slug: kinetics -.. has_math: true -.. title: Modeling Chemical Reactions - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Modeling Chemical Reactions in Cantera</h1> - - .. class:: lead - - Here, we describe how Cantera calculates chemical reaction rates for various - reaction types. - -.. _sec-elementary: - -Elementary Reactions --------------------- - -The basic reaction type is a homogeneous reaction with a pressure-independent -rate coefficient and mass action kinetics. For example: - -.. math:: - - \mathrm{A + B \rightleftharpoons C + D} - -with a forward rate constant :math:`k_f` defined as a modified Arrhenius function: - -.. math:: - - k_f = A T^b e^{-E_a / RT} - -where :math:`A` is the pre-exponential factor, :math:`T` is the temperature, -:math:`b` is the temperature exponent, :math:`E_a` is the activation energy, -and :math:`R` is the gas constant. The forward reaction rate is then calculated -as: - -.. math:: - - R_f = [\mathrm{A}] [\mathrm{B}] k_f - -An elementary reaction can be defined in the YAML format using the -:ref:`elementary <sec-yaml-elementary>` reaction ``type``. - -In YAML, the reaction ``type`` entry can be omitted, as it represents the default. In -case the ``type`` entry is omitted and a species occurs on both sides, Cantera -infers that the reaction type is :ref:`three-body <sec-yaml-three-body>`. - -Three-Body Reactions --------------------- - -A three-body reaction is a gas-phase reaction of the form: - -.. math:: - - \mathrm{A + B + M \rightleftharpoons AB + M} - -Here :math:`\mathrm{M}` is an unspecified collision partner that carries away excess energy to -stabilize the :math:`\mathrm{AB}` molecule (forward direction) or supplies energy to break the -:math:`\mathrm{AB}` bond (reverse direction). In addition to the generic collision partner -:math:`\mathrm{M}`, it is also possible to explicitly specify a colliding species. In this case, -the reaction type is automatically inferred by Cantera. - -Different species may be more or less effective in acting as the collision partner. A species that -is much lighter than :math:`\mathrm{A}` and :math:`\mathrm{B}` may not be able to transfer much of -its kinetic energy, and so would be inefficient as a collision partner. On the other hand, a species -with a transition from its ground state that is nearly resonant with one in the -:math:`\mathrm{AB^*}` activated complex may be much more effective at exchanging energy than would -otherwise be expected. - -These effects can be accounted for by defining a collision efficiency -:math:`\epsilon` for each species, defined such that the forward reaction rate is - -.. math:: - - R_f = [\mathrm{A}][\mathrm{B}][\mathrm{M}]k_f(T) - -where - -.. math:: - - [\mathrm{M}] = \sum_{k} \epsilon_k C_k - -where :math:`C_k` is the concentration of species :math:`k`. Since any constant -collision efficiency can be absorbed into the rate coefficient :math:`k_f(T)`, the default collision -efficiency is 1.0. - -*New in Cantera 3.0*: The rate coefficient :math:`k_f(T)` may be implemented using any -rate parameterization supported by Cantera, not just the modified Arrhenius form. - -Sometimes, accounting for a particular third body's collision efficiency may require an -alternate set of rate parameters entirely. In this case, two reactions are written: - -.. math:: - - \mathrm{A + B + M \rightleftharpoons AB + M \quad (R1)} - - \mathrm{A + B + C \rightleftharpoons AB + C \quad (R2)} - -where the third-body efficiency for C in the first reaction is set to zero. - -A three-body reaction may be defined in the YAML format using the -:ref:`three-body <sec-yaml-three-body>` reaction ``type``. - -*Changed in Cantera 3.0*: The ``type`` field of the YAML entry may be omitted. Reactions -containing the generic third body M (as in R1) 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 (as in reaction R2) -- All reactants and products have integral stoichiometric coefficients -- The sum of the stoichiometric coefficients for either the reactants or products is 3. - -If the third body efficiency of C in R1 is not set to zero, these are considered -duplicate reactions and must be marked as such. - -Falloff Reactions ------------------ - -A falloff reaction is one that has a rate that is first-order in :math:`[\mathrm{M}]` at low -pressure, like a three-body reaction, but becomes zero-order in :math:`[\mathrm{M}]` as :math:`[\mathrm{M}]` -increases. Dissociation/association reactions of polyatomic molecules often -exhibit this behavior. - -The simplest expression for the rate coefficient for a falloff reaction is the -Lindemann form [#Lindemann1922]_: - -.. math:: - - k_f(T, [{\mathrm{M}}]) = \frac{k_0[{ \mathrm{M}}]}{1 + \frac{k_0{ [\mathrm{M}]}}{k_\infty}} - -In the low-pressure limit, this approaches :math:`k_0{[\mathrm{M}]}`, and in the -high-pressure limit it approaches :math:`k_\infty`. - -Defining the non-dimensional reduced pressure: - -.. math:: - - P_r = \frac{k_0 [\mathrm{M}]}{k_\infty} - -The rate constant may be written as - -.. math:: - - k_f(T, P_r) = k_\infty \left(\frac{P_r}{1 + P_r}\right) - -More accurate models for unimolecular processes lead to other, more complex, -forms for the dependence on reduced pressure. These can be accounted for by -multiplying the Lindemann expression by a function :math:`F(T, P_r)`: - -.. math:: - - k_f(T, P_r) = k_\infty \left(\frac{P_r}{1 + P_r}\right) F(T, P_r) - -This expression is used to compute the rate coefficient for falloff -reactions. The function :math:`F(T, P_r)` is the falloff function. - -A falloff reaction may be defined in the YAML format using the -:ref:`falloff <sec-yaml-falloff>` reaction ``type``. - -The Troe Falloff Function -~~~~~~~~~~~~~~~~~~~~~~~~~ - -A widely-used falloff function is the one proposed by Gilbert et -al. [#Gilbert1983]_: - -.. math:: - - \log_{10} F(T, P_r) = \frac{\log_{10} F_{cent}(T)}{1 + f_1^2} - - F_{cent}(T) = (1-A) \exp(-T/T_3) + A \exp (-T/T_1) + \exp(-T_2/T) - - f_1 = (\log_{10} P_r + C) / (N - 0.14 (\log_{10} P_r + C)) - - C = -0.4 - 0.67\; \log_{10} F_{cent} - - N = 0.75 - 1.27\; \log_{10} F_{cent} - -A Troe falloff function may be specified in the YAML format using the -:ref:`Troe <sec-yaml-falloff>` field in the reaction entry. The first -three parameters, :math:`(A, T_3, T_1)`, are required. The fourth parameter, -:math:`T_2`, is optional; if omitted, the last term of the falloff function is -not used. - -Tsang's Approximation to :math:`F_{cent}` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Wing Tsang presented approximations for the value of :math:`F_{cent}` for Troe -falloff in databases of reactions, for example, Tsang and Herron [#Tsang1991]_. -Tsang's approximations are linear in temperature: - -.. math:: - F_{cent} = A + BT - -where :math:`A` and :math:`B` are constants. The remaining equations for :math:`C`, -:math:`N`, :math:`f_1`, and :math:`F` from Troe falloff are not affected: - -.. math:: - - \log_{10} F(T, P_r) = \frac{\log_{10} F_{cent}(T)}{1 + f_1^2} - - f_1 = (\log_{10} P_r + C) / (N - 0.14 (\log_{10} P_r + C)) - - C = -0.4 - 0.67\; \log_{10} F_{cent} - - N = 0.75 - 1.27\; \log_{10} F_{cent} - -A Tsang falloff function may be specified in the YAML format using the -:ref:`Tsang <sec-yaml-falloff>` field in the reaction entry. *(New in Cantera 2.6)* - -.. _sec-sri-falloff: - -The SRI Falloff Function -~~~~~~~~~~~~~~~~~~~~~~~~ - -This falloff function is based on the one originally due to Stewart et al. [#Stewart1989]_, which -required three parameters :math:`a`, :math:`b`, and :math:`c`. Kee et al. [#Kee1989]_ generalized -this function slightly by adding two more parameters :math:`d` and :math:`e`. (The original form -corresponds to :math:`d = 1` and :math:`e = 0`.) Cantera supports the extended 5-parameter form, -given by: - -.. math:: - - F(T, P_r) = d \bigl[a \exp(-b/T) + \exp(-T/c)\bigr]^{1/(1+\log_{10}^2 P_r )} T^e - -In keeping with the nomenclature of Kee et al. [#Kee1989]_, we will refer to this as -the **SRI falloff function**. - -An SRI falloff function may be specified in the YAML format using the -:ref:`SRI <sec-yaml-falloff>` field in the entry. - -Chemically-Activated Reactions ------------------------------- - -For these reactions, the rate falls off as the pressure increases, due to -collisional stabilization of a reaction intermediate. Example: - -.. math:: - - \mathrm{Si + SiH_4 (+M) \leftrightarrow Si_2H_2 + H_2 (+M)} - -which competes with: - -.. math:: - - \mathrm{Si + SiH_4 (+M) \leftrightarrow Si_2H_4 (+M)} - -Like falloff reactions, chemically-activated reactions are described by -blending between a low-pressure and a high-pressure rate expression. The -difference is that the forward rate constant is written as being proportional -to the *low-pressure* rate constant: - -.. math:: - - k_f(T, P_r) = k_0 \left(\frac{1}{1 + P_r}\right) F(T, P_r) - -and the optional blending function :math:`F` may described by any of the -parameterizations allowed for falloff reactions. - -Chemically-activated reactions can be defined in the YAML format using -the :ref:`chemically-activated <sec-yaml-chemically-activated>` reaction ``type``. - -Pressure-Dependent Arrhenius Rate Expressions (P-Log) ------------------------------------------------------ - -This parameterization represents pressure-dependent reaction rates -by logarithmically interpolating between Arrhenius rate expressions at various -pressures. Given two rate expressions at two specific pressures: - -.. math:: - - P_1: k_1(T) = A_1 T^{b_1} e^{-E_1 / RT} - - P_2: k_2(T) = A_2 T^{b_2} e^{-E_2 / RT} - -The rate at an intermediate pressure :math:`P_1 < P < P_2` is computed as - -.. math:: - - \log k(T,P) = \log k_1(T) + \bigl(\log k_2(T) - \log k_1(T)\bigr) - \frac{\log P - \log P_1}{\log P_2 - \log P_1} - -Multiple rate expressions may be given at the same pressure, in which case the -rate used in the interpolation formula is the sum of all the rates given at that -pressure. For pressures outside the given range, the rate expression at the nearest -pressure is used. - -Negative A-factors can be used for any of the rate expressions at a given pressure. -However, the sum of all of the rates at a given pressure **must** be positive, due -to the logarithmic interpolation of the rate for intermediate pressures. When a -P-log type reaction is initialized, Cantera does a validation check for a range of -temperatures that the sum of the reaction rates at each pressure is positive. Unfortunately, if -these checks fail, the only options are to remove the reaction or contact the author -of the reaction/mechanism in question, because the reaction is mathematically unsound. - -P-log reactions can be defined in the YAML format using the -:ref:`pressure-dependent-Arrhenius <sec-yaml-pressure-dependent-Arrhenius>` -reaction ``type``. - -Chebyshev Reaction Rate Expressions ------------------------------------ - -Chebyshev rate expressions represent a phenomenological rate coefficient -:math:`k(T,P)` in terms of a bivariate Chebyshev polynomial. The rate constant -can be written as: - -.. math:: - - \log k(T,P) = \sum_{t=1}^{N_T} \sum_{p=1}^{N_P} \alpha_{tp} - \phi_t(\tilde{T}) \phi_p(\tilde{P}) - -where :math:`\alpha_{tp}` are the constants defining the rate, :math:`\phi_n(x)` -is the Chebyshev polynomial of the first kind of degree :math:`n` evaluated at -:math:`x`, and - -.. math:: - - \tilde{T} \equiv \frac{2T^{-1} - T_\mathrm{min}^{-1} - T_\mathrm{max}^{-1}} - {T_\mathrm{max}^{-1} - T_\mathrm{min}^{-1}} - - \tilde{P} \equiv \frac{2 \log P - \log P_\mathrm{min} - \log P_\mathrm{max}} - {\log P_\mathrm{max} - \log P_\mathrm{min}} - -are reduced temperatures and reduced pressures which map the ranges -:math:`(T_\mathrm{min}, T_\mathrm{max})` and :math:`(P_\mathrm{min}, -P_\mathrm{max})` to :math:`(-1, 1)`. - -A Chebyshev rate expression is specified in terms of the coefficient matrix -:math:`\alpha` and the temperature and pressure ranges. - -Note that the Chebyshev polynomials are not defined outside the interval -:math:`(-1,1)`, and therefore extrapolation of rates outside the range of -temperatures and pressure for which they are defined is strongly discouraged. - -Chebyshev reactions can be defined in the YAML format using the -:ref:`Chebyshev <sec-yaml-Chebyshev>` reaction ``type``. - -.. _sec-Blowers-Masel: - -Blowers-Masel Reactions ------------------------ - -In some circumstances like thermodynamic sensitivity analysis, or -modeling heterogeneous reactions from one catalyst surface to another, -the enthalpy change of a reaction (:math:`\Delta H`) can be modified. Due to the change in :math:`\Delta H`, -the activation energy of the reaction must be adjusted accordingly to provide accurate simulation results. To -adjust the activation energy due to changes in the reaction enthalpy, the Blowers-Masel rate expression is -available. This approximation was proposed by Blowers and Masel [#BlowersMasel2000]_ to automatically -scale activation energy as the reaction enthalpy is changed. -The activation energy estimation can be written as: - -.. math:: - - E_a = \begin{cases} - 0 & \text{if } \Delta H \leq -4 E_a^0 \\ - \Delta H & \text{if } \Delta H \geq 4 E_a^0 \\ - \frac{\left( w + \frac{\Delta H }{2} \right) (V_P - 2 w + \Delta H) ^2} - {V_P^2 - 4 w^2 + \Delta H^2} & \text{Otherwise} - \end{cases} - -where - -.. math:: - - V_P = 2 w \frac{w + E_a^0}{w - E_a^0}, - -:math:`w` is the average of the bond dissociation energy of the bond breaking and that being formed, -:math:`E_a^0` is the intrinsic activation energy, and :math:`\Delta H` is the enthalpy change of the reaction. -Note that the expression is insensitive to :math:`w` as long as :math:`w \ge 2 E_a^0`, so we can use -an arbitrarily high value of :math:`w = 1000\text{ kJ/mol}`. - -After :math:`E_a` is evaluated, the reaction rate can be calculated using the modified Arrhenius expression - -.. math:: - - k_f = A T^b e^{-E_a / RT}. - -.. TODO: Update the link once version 2.6 is released - -Blowers Masel reactions can be defined in the YAML format using the -`Blowers-Masel <https://cantera.org/documentation/dev/sphinx/html/yaml/reactions.html#sec-yaml-blowers-masel>`__ reaction ``type``. -*(New in Cantera 2.6)* - -.. _sec-surface: - -Surface Reactions ------------------ - -Heterogeneous reactions on surfaces are represented by an extended Arrhenius- -like rate expression, which combines the modified Arrhenius rate expression with -further corrections dependent on the fractional surface coverages -:math:`\theta_{k}` of one or more surface species. The forward rate constant for a -reaction of this type is: - -.. math:: - - k_f = A T^b \exp \left( - \frac{E_a}{RT} \right) - \prod_k 10^{a_k \theta_k} - \theta_k^{m_k} - \exp \left( \frac{- E_k \theta_k}{RT} \right) - -where :math:`A`, :math:`b`, and :math:`E_a` are the modified Arrhenius -parameters and :math:`a_k`, :math:`m_k`, and :math:`E_k` are the coverage -dependencies from species :math:`k`. - -In the YAML format, surface reactions are identified by the presence -of surface species and support several -`additional options <https://cantera.org/documentation/dev/sphinx/html/yaml/reactions.html#interface-arrhenius>`__. - -.. TODO: Update links once version 2.6 is released - -In YAML, the surface reaction ``type`` defaults to ``interface-Arrhenius``, where -the rate expression uses the :ref:`Arrhenius <sec-elementary>` parameterization (see -`YAML documentation <https://cantera.org/documentation/dev/sphinx/html/yaml/reactions.html#interface-arrhenius>`__). -As an alternative, Cantera also supports the ``interface-Blowers-Masel`` surface -reaction ``type``, which uses the :ref:`Blowers-Masel <sec-Blowers-Masel>` -parameterization (see -`YAML documentation <https://cantera.org/documentation/dev/sphinx/html/yaml/reactions.html#interface-blowers-masel>`__; -*New in Cantera 2.6*). - -.. _sec-sticking: - -Sticking Reactions ------------------- - -Sticking reactions represent a special case of surface reactions, where collisions -between gas-phase molecules and surfaces result in the gas-phase molecule sticking to -the surface. This process can be described as a reaction which is parameterized by a -sticking coefficient: - -.. math:: - - \gamma = a T^b e^{-c/RT} - -where :math:`a`, :math:`b`, and :math:`c` are constants specific to the -reaction. The values of these constants must be specified so that the sticking -coefficient :math:`\gamma` is between 0 and 1 for all temperatures. - -The sticking coefficient is related to the forward rate constant by the -formula: - -.. math:: - - k_f = \frac{\gamma}{\Gamma_\mathrm{tot}^m} \sqrt{\frac{RT}{2 \pi W}} - -where :math:`\Gamma_\mathrm{tot}` is the total molar site density, :math:`m` is -the sum of all the surface reactant stoichiometric coefficients, and :math:`W` -is the molecular weight of the gas phase species. - -Sticking reactions can be defined in the YAML format by specifying the rate constant -in the reaction's -`sticking-coefficient <https://cantera.org/documentation/dev/sphinx/html/yaml/reactions.html#sticking-arrhenius>`__ field. - -The sticking reaction ``type`` defaults to ``sticking-Arrhenius``, where -the rate expression uses the :ref:`Arrhenius <sec-elementary>` parameterization (see -`YAML documentation <https://cantera.org/documentation/dev/sphinx/html/yaml/reactions.html#sticking-arrhenius>`__). -As an alternative, Cantera also supports the ``sticking-Blowers-Masel`` surface -reaction ``type``, which uses the :ref:`Blowers-Masel <sec-Blowers-Masel>` -parameterization (see -`YAML documentation <https://cantera.org/documentation/dev/sphinx/html/yaml/reactions.html#sticking-blowers-masel>`__; -*New in Cantera 2.6*). - -.. _sec-plasma: - -Two-Temperature-Plasma Reactions --------------------------------- - -The two-temperature-plasma reaction is commonly used for non-equilibrium plasmas. The -reaction rate of a two-temperature-plasma reaction depends on both gas and electron -temperature [#Kossyi1992]_, and can be expressed as: - -.. math:: - - k_f = A T_e^b \exp \left( - \frac{E_{a,g}}{RT} \right) - \exp \left(\frac{E_{a,e}(T_e - T)}{R T T_e}\right), - -where :math:`A` is the pre-exponential factor, :math:`T` is the temperature, :math:`T_e` -is the electron temperature, :math:`b` is the electron temperature exponent, -:math:`E_{a,g}` is the activation energy for gas, :math:`E_{a,e}` is the activation -energy for electron and :math:`R` is the gas constant. *(New in Cantera 2.6)* - -.. _sec-additional-options: - -Additional Options ------------------- - -Reaction Orders -~~~~~~~~~~~~~~~ - -Explicit reaction orders different from the stoichiometric coefficients are -sometimes used for non-elementary reactions. For example, consider the global -reaction: - -.. math:: - - \mathrm{C_8H_{18} + 12.5 O_2 \rightarrow 8 CO_2 + 9 H_2O} - -the forward rate constant might be given as [#Westbrook1981]_: - -.. math:: - - k_f = 4.6 \times 10^{11} [\mathrm{C_8H_{18}}]^{0.25} [\mathrm{O_2}]^{1.5} - \exp\left(\frac{30.0\,\mathrm{kcal/mol}}{RT}\right) - -Special care is required in this case since the units of the pre-exponential -factor depend on the sum of the reaction orders, which may not be an integer. - -Note that you can change reaction orders only for irreversible reactions. - -Normally, reaction orders are required to be positive. However, in some cases -negative reaction orders are found to be better fits for experimental data. In -these cases, the default behavior may be overridden in the input file. - - -.. rubric:: References - -.. [#Lindemann1922] F. Lindemann. *Trans. Faraday Soc.*, 17:598, 1922. - -.. [#Gilbert1983] R. G. Gilbert, K. Luther, and - J. Troe. *Ber. Bunsenges. Phys. Chem.*, 87:169, 1983. - -.. [#Tsang1991] W. Tsang and J. Herron. *Journal of Physical and Chemical Reference Data*, 20:4, 1991. - -.. [#Stewart1989] P. H. Stewart, C. W. Larson, and D. Golden. - *Combustion and Flame*, 75:25, 1989. - -.. [#Kee1989] R. J. Kee, F. M. Rupley, and J. A. Miller. Chemkin-II: A Fortran - chemical kinetics package for the analysis of gas-phase chemical - kinetics. Technical Report SAND89-8009, Sandia National Laboratories, 1989. - -.. [#BlowersMasel2000] Blowers, P., & Masel, R. (2000). Engineering approximations - for activation energies in hydrogen transfer reactions. *AIChE Journal*, 46(10), - 2041-2052. https://doi.org/10.1002/aic.690461015 - -.. [#Westbrook1981] C. K. Westbrook and F. L. Dryer. Simplified reaction - mechanisms for the oxidation of hydrocarbon fuels in flames. *Combustion - Science and Technology* **27**, pp. 31--43. 1981. - -.. [#Kossyi1992] I. A. Kossyi, A. Y. Kostinsky, A. A. Matveyev. and V. P. - Kinetic scheme of the non-equilibrium discharge in nitrogen-oxygen mixtures. - mechanisms for the oxidation of hydrocarbon fuels in flames. - *Plasma Sources Science and Technology* **1**, no. 3, pp. 207. 1992. - DOI: https://doi.org/10.1088/0963-0252/1/3/011 diff --git a/pages/science/phase-thermo.rst b/pages/science/phase-thermo.rst deleted file mode 100644 index 6fc36d566..000000000 --- a/pages/science/phase-thermo.rst +++ /dev/null @@ -1,71 +0,0 @@ -.. slug: phase-thermo -.. has_math: true -.. title: Modeling Phases - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Modeling Phase Thermodynamics in Cantera</h1> - - .. class:: lead - - Here, we describe some of the most commonly-used phase models in Cantera. - -Bulk, Three-Dimensional Phases -############################## - -Ideal Gas Mixtures ------------------- - -Far and away, the most commonly-used phase model in Cantera is the **ideal gas** model. -Many combustion and CVD simulations make use of reacting ideal gas mixtures. The Cantera -ideal gas model allows any number of species, and any number of reactions among them. -It supports all of the options in the widely-used model described by Kee et al. -[#Kee1989]_, plus some additional options for species thermodynamic properties -and reaction rate expressions. - -Ideal gas mixtures can be defined in the YAML format by specifying -:ref:`ideal-gas <sec-yaml-ideal-gas>` in the ``thermo`` field. - -Stoichiometric Solid --------------------- - -A **stoichiometric solid** is one that is modeled as having a precise, fixed composition, -given by the composition of the one species present. A stoichiometric solid can be used to define a -condensed phase that can participate in heterogeneous reactions. (Of course, there cannot be -homogeneous reactions, since the composition is fixed.) - -A stoichiometric solid can be defined in the YAML format by specifying -:ref:`fixed-stoichiometry <sec-yaml-fixed-stoichiometry>` in the ``thermo`` field. - -Interfaces -########## - -Cantera presently implements a simple model for an interface between phases that treats it as a -two-dimensional ideal solution of interfacial species. There is a fixed site density :math:`n^0`, -and each site may be occupied by one of several adsorbates, or may be empty. The chemical potential -of each species is computed using the expression for an ideal solution: - -.. math:: - - \mu_k = \mu^0_k + RT \log \theta_k, - -where :math:`\theta_k` is the coverage of species :math:`k` on the surface. The coverage is related -to the surface concentration :math:`C_k` by - -.. math:: - - \theta_k = \frac{C_k n_k}{n^0} , - -where :math:`n_k` is the number of sites covered or blocked by species :math:`k`. - -An interface can be defined in the YAML format by specifying -:ref:`ideal-surface <sec-yaml-ideal-surface>` in the ``thermo`` field. - - -.. rubric:: References - -.. [#Kee1989] R. J. Kee, F. M. Rupley, and J. A. Miller. Chemkin-II: A Fortran - chemical kinetics package for the analysis of gasphase chemical - kinetics. Technical Report SAND89-8009, Sandia National Laboratories, 1989. diff --git a/pages/science/reactors/constpresmolereactor.rst b/pages/science/reactors/constpresmolereactor.rst deleted file mode 100644 index f22302e9e..000000000 --- a/pages/science/reactors/constpresmolereactor.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. title: Constant Pressure Reactor -.. has_math: true - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Constant Pressure Mole Reactor</h1> - - .. class:: lead - - This page shows the derivation of the governing equations used in - Cantera's Constant Pressure Mole Reactor model. - - More information on the Constant Pressure Mole Reactor class can be found `here. - <{{% ct_docs doxygen/html/d5/d7d/classCantera_1_1ConstPressureMoleReactor.html %}}>`__ - -Constant Pressure Mole Reactor -****************************** - -For this reactor model, the pressure is held constant. The energy equation is -defined by the total enthalpy. - -A Constant Pressure Mole Reactor is defined by the two state variables: - -- :math:`H`, the total enthalpy of the reactor's contents (in J) - -- :math:`n_k`, the number of moles for each species (in kmol) - -Using the definition of the total enthalpy: - -.. math:: - - H = U + pV - - \frac{d H}{d t} = \frac{d U}{d t} + p \frac{dV}{dt} + V \frac{dp}{dt} - -Noting that :math:`dp/dt = 0` and substituting into the energy equation yields: - -.. math:: - - \frac{dH}{dt} = \dot{Q} + \sum_{in} \dot{n}_{in} \bar{h}_{in} - - \bar{h} \sum_{out} \dot{n}_{out} - \tag{1} - -Where the total specific enthalpy :math:`h` is defined as :math:`h = \sum_k{\bar{h}_k n_k}`. -The enthalpy terms in equation 2 appear due to enthalpy flowing in and out -of the reactor. -The rate of heat transfer :math:`\dot{Q}` can replace :math:`\frac{d U}{d t} + p \frac{dV}{dt}` in the above equation due to the first law -of thermodynamics, which states :math:`\dot{Q} = \dot{H}` in a closed system where -no work is done. -Positive :math:`\dot{Q}` represents heat addition to the system. - -The moles of each species in the reactor's contents changes as a result of flow through -the reactor's inlets and outlets, and production of homogeneous gas phase species and reactions on the reactor :py:class:`Wall`. -The rate of moles of species :math:`k` generated through homogeneous phase -reactions is :math:`V \dot{\omega}_k`, and the total rate at which moles of species -:math:`k` changes is: - -.. math:: - - \frac{dn_k}{dt} = V \dot{\omega}_k + \sum_{in} \dot{n}_{k, in} - \sum_{out} \dot{n}_{k, out} + \dot{n}_{k, wall} - \tag{2} - -Where the subscripts *in* and *out* refer to the sum of the corresponding property -over all inlets and outlets respectively. A dot above a variable signifies a time -derivative. Reactor *Walls* are defined `here. <{{% ct_docs sphinx/html/cython/zerodim.html#cantera.Wall %}}>`__ - -Equations 1-2 are the governing equations for a Constant Pressure Mole Reactor. diff --git a/pages/science/reactors/constpresreactor.rst b/pages/science/reactors/constpresreactor.rst deleted file mode 100644 index 15e5e0028..000000000 --- a/pages/science/reactors/constpresreactor.rst +++ /dev/null @@ -1,95 +0,0 @@ -.. title: Constant Pressure Reactor -.. has_math: true - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Constant Pressure Reactor</h1> - - .. class:: lead - - This page shows the derivation of the governing equations used in - Cantera's Constant Pressure Reactor model. - - More information on the Constant Pressure Reactor class can be found `here. - <{{% ct_docs doxygen/html/d5/dfb/classCantera_1_1ConstPressureReactor.html %}}>`__ - -Constant Pressure Reactor -************************* - -For this reactor model, the pressure is held constant. The energy equation is -defined by the total enthalpy. - -A Constant Pressure Reactor is defined by the three state variables: - -- :math:`m`, the mass of the reactor's contents (in kg) - -- :math:`H`, the total enthalpy of the reactor's contents (in J) - -- :math:`Y_k`, the mass fractions for each species (dimensionless) - -The total mass of the reactor's contents changes as a result of flow through -the reactor's inlets and outlets, and production of homogeneous phase species -on the reactor :py:class:`Wall`: - -.. math:: - - \frac{dm}{dt} = \sum_{in} \dot{m}_{in} - \sum_{out} \dot{m}_{out} + - \dot{m}_{wall} - \tag{1} - -Where the subscripts *in* and *out* refer to the sum of the superscipted property -over all inlets and outlets respectively. A dot above a variable signifies a time -derivative. A Reactor *wall* is defined `here. -<{{% ct_docs sphinx/html/cython/zerodim.html#cantera.Wall %}}>`__ - -Using the definition of the total enthalpy: - -.. math:: - - H = U + pV - - \frac{d H}{d t} = \frac{d U}{d t} + p \frac{dV}{dt} + V \frac{dp}{dt} - -Noting that :math:`dp/dt = 0` and substituting into the energy equation yields: - -.. math:: - - \frac{dH}{dt} = \dot{Q} + \sum_{in} \dot{m}_{in} h_{in} - - h \sum_{out} \dot{m}_{out} - \tag{2} - -Where the total specific enthalpy :math:`h` is defined as :math:`h = \sum_k{h_k Y_k}`. -The enthalpy terms in equation 2 appear due to enthalpy flowing in and out -of the reactor. The rate of heat transfer :math:`\dot{Q}` can replace -:math:`\frac{d U}{d t} + p \frac{dV}{dt}` in the above equation due to the first law -of thermodynamics, which states :math:`\dot{Q} = \dot{H}` in a closed system where -no work is done. Positive :math:`\dot{Q}` represents heat addition to the system. - -The rate at which species :math:`k` is generated through homogeneous phase -reactions is :math:`V \dot{\omega}_k W_k`, and the total rate at which species -:math:`k` is generated is: - -.. math:: - - \dot{m}_{k,gen} = V \dot{\omega}_k W_k + \dot{m}_{k,wall} - -The rate of change in the mass of each species is: - -.. math:: - - \frac{d(mY_k)}{dt} = \sum_{in} \dot{m}_{in} Y_{k,in} - - \sum_{out} \dot{m}_{out} Y_k + - \dot{m}_{k,gen} - -Expanding the derivative on the left hand side and substituting the equation -for :math:`dm/dt`, the equation for each homogeneous phase species is: - -.. math:: - - m \frac{dY_k}{dt} = \sum_{in} \dot{m}_{in} (Y_{k,in} - Y_k)+ - \dot{m}_{k,gen} - Y_k \dot{m}_{wall} - \tag{3} - -Equations 1-3 are the governing equations for a Constant Pressure Reactor. \ No newline at end of file diff --git a/pages/science/reactors/controlreactor.rst b/pages/science/reactors/controlreactor.rst deleted file mode 100644 index b26e08a02..000000000 --- a/pages/science/reactors/controlreactor.rst +++ /dev/null @@ -1,99 +0,0 @@ -.. title: Control Volume Reactor -.. has_math: true - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Control Volume Reactor</h1> - - .. class:: lead - - This page shows the derivation of the governing equations used in - Cantera's Control Volume Reactor model. - - More information on the Control Volume Reactor class can be found `here. - <{{% ct_docs doxygen/html/dc/d5e/classCantera_1_1Reactor.html %}}>`__ - -Control Volume Reactor -********************** - -A homogeneous zero-dimensional reactor. By default, they are closed (no inlets or outlets), -have fixed volume, and have adiabatic, chemically-inert walls. These properties may all be -changed by adding appropriate components such as :py:class:`Wall`, :py:class:`ReactorSurface`, -:py:class:`MassFlowController`, and :py:class:`Valve`. - -A Control Volume Reactor is defined by the four state variables: - -- :math:`m`, the mass of the reactor's contents (in kg) - -- :math:`V`, the reactor volume (in m\ :sup:`3`) - -- :math:`U`, the total internal energy of the reactors contents (in J) - -- :math:`Y_k`, the mass fractions for each species (dimensionless) - -The total mass of the reactor's contents changes as a result of flow through -the reactor's inlets and outlets, and production of homogeneous phase species -on the reactor :py:class:`Wall`. - -.. math:: - - \frac{dm}{dt} = \sum_{in} \dot{m}_{in} - \sum_{out} \dot{m}_{out} + - \dot{m}_{wall} - \tag{1} - -Where the subscripts *in* and *out* refer to the sum of the corresponding property -over all inlets and outlets respectively. A dot above a variable signifies a time -derivative. - -The reactor volume changes as a function of time due to the motion of one or -more walls: - -.. math:: - - \frac{dV}{dt} = \sum_w f_w A_w v_w(t) - \tag{2} - -where :math:`f_w = \pm 1` indicates the facing of the wall (whether moving the wall increases or -decreases the volume of the reactor), :math:`A_w` is the -surface area of the wall, and :math:`v_w(t)` is the velocity of the wall as a -function of time. - -The equation for the total internal energy is found by writing the first law -for an open system: - -.. math:: - - \frac{dU}{dt} = - p \frac{dV}{dt} + \dot{Q} + - \sum_{in} \dot{m}_{in} h_{in} - h \sum_{out} \dot{m}_{out} - \tag{3} - -Where :math:`\dot{Q}` is the net rate of heat addition to the system. - -The rate at which species :math:`k` is generated through homogeneous phase -reactions is :math:`V \dot{\omega}_k W_k`, and the total rate at which species -:math:`k` is generated is: - -.. math:: - - \dot{m}_{k,gen} = V \dot{\omega}_k W_k + \dot{m}_{k,wall} - -The rate of change in the mass of each species is: - -.. math:: - - \frac{d(mY_k)}{dt} = \sum_{in} \dot{m}_{in} Y_{k,in} - - \sum_{out} \dot{m}_{out} Y_k + - \dot{m}_{k,gen} - -Expanding the derivative on the left hand side and substituting the equation -for :math:`dm/dt`, the equation for each homogeneous phase species is: - -.. math:: - - m \frac{dY_k}{dt} = \sum_{in} \dot{m}_{in} (Y_{k,in} - Y_k)+ - \dot{m}_{k,gen} - Y_k \dot{m}_{wall} - \tag{4} - -Equations 1-4 are the governing equations for a Control Volume Reactor. \ No newline at end of file diff --git a/pages/science/reactors/cvodes.rst b/pages/science/reactors/cvodes.rst deleted file mode 100644 index 6aa98fe04..000000000 --- a/pages/science/reactors/cvodes.rst +++ /dev/null @@ -1,284 +0,0 @@ -.. title: CVODES and Time Integration in Cantera -.. has_math: true - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Time Integration in Cantera using SUNDIALS</h1> - - .. class:: lead - - This guide explains ways Cantera can solve the governing equations of - a transient Reactor Network problem. Additional insights - into the integrator library SUNDIALS utilized by Cantera are also provided. - -Using Cantera to Advance a Reactor Network in Time -************************************************** - -A ``ReactorNet`` can be advanced in time by one of the following three -methods: - -- ``step()``: The ``step()`` method computes the state of the system after one - time step. The size of the step is determined by SUNDIALS when the method is called. - SUNDIALS determines the step size by estimating the local error at every step, which - must satisfy tolerance conditions. The step is redone with reduced step size whenever - that error test fails. SUNDIALS also periodically checks if the maximum step size is - being used. The time step must not be larger than a predefined maximum time step - :math:`\Delta t_{\mathrm{max}}`. The new time :math:`t_{\mathrm{new}}` at the end - of the single step is returned by this function. This method produces the highest time - resolution in the output data of the methods implemented in Cantera. - -- ``advance(t_new)``: This method computes the state of the system at the - user-provided time :math:`t_{\mathrm{new}}`. :math:`t_{\mathrm{new}}` is the absolute - time from the initial time of the system. Although the user specifies the time when - integration should stop, SUNDIALS chooses the time step size as the network is integrated. - Many of these internal SUNDIALS time steps are usually required to reach - :math:`t_{\mathrm{new}}`. As such, ``advance(t_new)`` preserves the accuracy of using - ``step()`` but allows consistent time step spacing in the output data. - -- ``advance_to_steady_state(max_steps, residual_threshold, atol, - write_residuals)`` [Python interface only]: If the steady state solution of a - reactor network is of interest, this method can be used. Internally, the - steady state is approached by time stepping. The network is considered to be - at steady state if the feature-scaled residual of the state vector is below a - given threshold value (which by default is 10 times the time step ``rtol``). - -The ``advance(t_new)`` is typically used when consistent, regular, time steps are -required in the output data. This usually simplifies comparisons among many -simulation results at a single time point. However, some detail, for example, a -fast ignition process, might not be resolved in the output data if the user-provided -time step is not small enough. - -To avoid losing this detail, the -`Reactor::setAdvanceLimit <{{% ct_docs doxygen/html/dc/d5e/classCantera_1_1Reactor.html#a9b630edc7d836e901886d7fd81134d9e %}}>`__ -method (C++) or the :py:func:`Reactor.set_advance_limit` method (Python) can be -used to set the maximum amount that a specified solution component can change -between output times. For an example of this feature's use, see the example -`reactor1.py </examples/python/reactors/reactor1.py.html>`__. However, as a tradeoff, -the time step sizes in the output data are no longer guaranteed to be uniform. - -Even though Cantera comes pre-defined with typical parameters for tolerances -and the maximum internal time step, the solver may not be correctly configured -for the specific system. In this case the internal timestep solutions may not -converge towards a single value. To solve this problem, three parameters can be -tuned: The absolute time stepping tolerances, the relative time stepping tolerances, -and the maximum time step. A reduction of the latter value is particularly useful -when dealing with abrupt changes in the boundary conditions (for example, -opening/closing valves; see also the `IC engine example </examples/python/reactors -/ic_engine.py.html>`__). - -How Does Cantera's Reactor Network Time Integration Feature Actually Work? -========================================================================== - -A description of the science behind Cantera's reactor network -simulation capabilities is available on the Cantera website, -`here <https://cantera.org/science/reactors/reactors.html>`__. This section will go into more -developer-oriented detail about how the last step, ``ReactorNet``'s -`time integration methods <https://cantera.org/science/reactors/reactors.html#time- -integration-for-reactor-networks>`__, actually work. A ``ReactorNet`` object doesn't -perform time integration on its own. Cantera generates a Jacobian array for the set -of ``Reactor`` objects contained in the ``ReactorNet``. This Jacobian, along with -functions to evaluate the residual of each ODE representing the system, is passed to -an ``Integrator``. - -Following integration from Reactor Network creation to completion ------------------------------------------------------------------ - -Step 1: Reactor(s) created in Reactor Network -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -First, let's take a look at a basic example to see how we might utilize Cantera's time integration -functionality. We'll simulate an isolated reactor in Python that is homogeneously filled by a gas -mixture (the gas state used in this example is arbitrary, but interesting because it's -explosive). Then we'll advance the simulation in time to an (arbitrary) absolute time of -1 second, noting the changes in the state of the gas. - -.. code-block:: python - - import cantera as ct # import Cantera's Python module - - gas = ct.Solution("gri30.yaml") # create a default GRI-Mech 3.0 gas mixture - gas.TPX = 1000.0, ct.one_atm, "H2:2,O2:1,N2:4" # set gas to an interesting state - reac = ct.IdealGasReactor(gas) # create a reactor containing the gas - sim = ct.ReactorNet([reac]) # add the reactor to a new ReactorNet simulator - gas() # view the initial state of the mixture (state summary will be printed to console) - sim.advance(1) # advance the simulation to the specified absolute time, t = 1 sec - gas() # view the updated state of the mixture, reflecting properties at t = 1 sec - -For a more advanced example that adds inlets and outlets to the reactor, see Cantera's combustor example -(`Python </examples/python/reactors/combustor.py.html>`__ -| `C++ </examples/cxx/combustor.html>`__). Additional examples can be found in the -`Python Reactor Network Examples <https://cantera.org/examples/python/index.html#python-example- -reactors>`__ section of the Cantera website. - -Optional Preconditioning -^^^^^^^^^^^^^^^^^^^^^^^^ - -Some mole reactors are capable of leveraging preconditioning to accelerate integration of the system. -The former code can be modified as follows to use preconditioning. -The preconditioner can also be assigned to a python object and tunable parameters can adjusted. - -.. code-block:: python - - import cantera as ct # import Cantera's Python module - - gas = ct.Solution("gri30.yaml") # create a default GRI-Mech 3.0 gas mixture - gas.TPX = 1000.0, ct.one_atm, "H2:2,O2:1,N2:4" # set gas to an interesting state - reac = ct.IdealGasMoleReactor(gas) # create a reactor containing the gas - sim = ct.ReactorNet([reac]) # add the reactor to a new ReactorNet simulator - sim.preconditioner = ct.AdaptivePreconditioner() # add preconditioner to the network - gas() # view the initial state of the mixture (state summary will be printed to console) - sim.advance(1) # advance the simulation to the specified absolute time, t = 1 sec - gas() # view the updated state of the mixture, reflecting properties at t = 1 sec - -Step 2: ``advance()`` method called -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In any case, after properly configuring a reactor network and its components in Cantera, a call to the -``ReactorNet``'s ``advance()`` method can be used to predict the state of the network at a specified time. -The initial condition information is passed off to the `Integrator` when calling `advance()`. -Transient physical and chemical interactions are simulated by integrating the network's system of ODE -governing equations through time, a process that's actually performed by an external `Integrator` object. - -Step 3: Information about current gas state provided to an `Integrator` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``Integrator`` class is Cantera's interface for ODE/DAE system integrators. - -``Integrator`` is a `polymorphic base class <http://www.cplusplus.com/doc/tutorial/polymorphism/>`__; it -defines a set of *virtual* methods that derived classes (the actual system integrators) will -provide implementations for. - -The ``newIntegrator()`` factory method creates and returns an ``Integrator`` object of -the specified type. Calling ``newIntegrator("CVODE")`` creates a new ``CVodesIntegrator`` -object for integrating an ODE system, while calling ``newIntegrator("IDA")`` creates a -new ``IdasIntegrator`` object for integrating a DAE system. The appropriate integrator -type is determined by the ``ReactorNet`` class based on the types of the installed -reactors. Below, the implementation of ``CvodesIntegrator`` is described; the -``IdasIntegrator`` works in a similar way, though the function names are different. - -Step 4: Communicate with SUNDIALS using a wrapper function -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Because SUNDIALS is written in C, the ``CVodesIntegrator`` C++ wrapper is used to access the solver. -The ``CVodesIntegrator`` class is a C++ wrapper class for ``CVODES``. (`Documentation -<{{% ct_docs doxygen/html/d9/d6b/classCantera_1_1CVodesIntegrator.html %}}>`__) -The ``CVodesIntegrator`` class makes the appropriate call to the ``CVODES`` driver function, ``CVode()``. - -Step 5: ``Cvode()`` driver function is called -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Method ``CVode()`` is the main driver of the ``CVODES`` package. ``CVode()`` integrates over a time interval defined by -the user, by calling ``cvStep()`` to do internal time steps (not specified by the user). (*Documentation:* -see `CVODES User Guide <https://sundials.readthedocs.io/en/latest/cvodes/index.html>`__) - -The arguments taken by the ``CVode()`` method is shown below: - -.. code-block:: C++ - - int CVode(void *cvode_mem, realtype tout, N_Vector yout, realtype *tret, int itask); - -There are some interesting things to note about this call to ``CVode()``: - -- ``m_cvode_mem`` is a pointer to the block of memory that was allocated and configured during initialization. -- After execution, ``m_y`` will contain the computed solution vector, and will later be used to update the ``ReactorNet`` - to its time-integrated state. -- The ``CV_NORMAL`` option tells the solver that it should continue taking internal timesteps until it has reached - user-specified ``tout`` (or just passed it, in which case solutions are reached by interpolation). This provides the - appropriate functionality for ``ReactorNet::advance()``. The alternate option, ``CV_ONE_STEP``, tells the solver to take - a single internal step, and is used in ``ReactorNet::step()``. - -The result of the ``CVode()`` method is assigned to the ``flag`` object. ``CVode()`` returns 1 or 0, corresponding to -a successful or unsuccessful integration, respectively. - -.. code-block:: C++ - - int flag = CVode(m_cvode_mem, tout, m_y, &m_time, CV_NORMAL); - -Step 6: ``FuncEval`` class describes ODEs to solve -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -How does ``CVODES`` know what ODE system it should be solving? - -The ODE system was actually already specified using ``CVodeInit()``, one of the methods automatically invoked during the -``ReactorNet::initialize()`` routine. ``CVODES`` requires that its user provide a C function that defines their ODE, -able to compute the right-hand side of the ODE system (dy/dt) for a given value of the independent variable, `t`, -and the state vector, ``y``. For more information about ODE right-hand side function requirements, -see `CVODES User Guide <https://sundials.readthedocs.io/en/latest/cvodes/Usage/SIM.html#user-supplied-functions>`__. - -The ``CVodesIntegrator`` wrapper class provides a useful C++ interface for configuring this C function by pairing with -``FuncEval``, an abstract base class for ODE right-hand-side function evaluators (`Documentation -<{{% ct_docs doxygen/html/d1/dd1/classCantera_1_1FuncEval.html %}}>`__). Classes derived -from ``FuncEval`` will implement the evaluation of the provided ODE system. - -An ODE right-hand-side evaluator is always needed in the ODE solution process (it's the only way to describe the system!), and for that reason a `FuncEval` object is a required parameter -when initializing any type of ``Integrator``. - -Let's take a look at how ``ReactorNet`` implements this ``FuncEval`` object. ``ReactorNet`` actually points to itself when -defining a ``FuncEval`` type, meaning it defines *itself* as a ``FuncEval`` derivative. - -Then, ``ReactorNet`` initializes the ``Integrator``, using a reference to itself (as a ``FuncEval``) from the -`this <https://en.cppreference.com/w/cpp/language/this>`__ pointer. - -To be a valid ``FuncEval`` object, a ``ReactorNet`` needs to provide implementations for all of ``FuncEval``'s -virtual functions, particularly the actual ODE right-hand-side computation -function, ``FuncEval::eval()``. Note that this is declared as a `pure virtual -<https://en.cppreference.com/w/cpp/language/abstract_class>`__ function, which makes -``FuncEval`` an abstract class. - -To evaluate the reactor governing equations the following parameters must be known: - -#. ``t``: Current time in seconds. -#. ``LHS``: pointer to start of vector of left-hand side coefficients for governing equations. - Has length m_nv, default values 1. -#. ``RHS``: pointer to start of vector of right-hand side coefficients for governing equations. - Has length m_nv, default values 0. - -.. code-block:: C++ - - virtual void eval(double t, double* LHS, double* RHS); - -``eval()`` is called by ``ReactorNet::eval``. - -The above code shows the necessary inputs for solving the ODEs using the ``eval()`` function. ``eval()`` takes in the -value of each state variable derivative (``ydot``) at a time ``t``, and will write the integrated values for each -state variable to the solution vector (``y``). - -Step 7: ``eval()`` is called to solve provided ODEs -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Along with the rest of ``FuncEval``'s virtual functions, an appropriate override is provided for ``FuncEval::eval()`` in -``ReactorNet`` - -.. code-block:: C++ - - void ReactorNet::eval(double t, double* y, double* ydot, double* p) - { - m_time = t; - updateState(y); - m_LHS.assign(m_nv, 1); - m_RHS.assign(m_nv, 0); - for (size_t n = 0; n < m_reactors.size(); n++) { - m_reactors[n]->applySensitivity(p); - m_reactors[n]->eval(t, m_LHS.data() + m_start[n], m_RHS.data() + m_start[n]); - size_t yEnd = 0; - if (n == m_reactors.size() - 1) { - yEnd = m_RHS.size(); - } else { - yEnd = m_start[n + 1]; - } - for (size_t i = m_start[n]; i < yEnd; i++) { - ydot[i] = m_RHS[i] / m_LHS[i]; - } - m_reactors[n]->resetSensitivity(p); - } - checkFinite("ydot", ydot, m_nv); - } - - -``ReactorNet``'s ``eval()`` method evaluates the governing equations of all ``Reactors`` -contained in the network. This brings us right back to where we started. For more -information, see Cantera's `reactor network science page </science/reactors/reactors.html>`__. - -This documentation is based off @paulblum's `blog post <https://cantera.org/blog/gsoc-2020-blog-3.html>`__. diff --git a/pages/science/reactors/extensiblereactor.rst b/pages/science/reactors/extensiblereactor.rst deleted file mode 100644 index ebd984f6e..000000000 --- a/pages/science/reactors/extensiblereactor.rst +++ /dev/null @@ -1,156 +0,0 @@ -.. title: Extensible Reactors in Cantera -.. has_math: true - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Extensible Reactor</h1> - - .. class:: lead - - This page walks through the walks through defining modified governing equations - and shows how to implement these changes to the equations in Python. - -Extensible Reactor Tutorial -*************************** - -The variables in the governing equations that are differentiated with respect to time -are known as the state variables. The state variables depend on the type of Reactor -base class chosen. For example, choosing an `Ideal Gas Constant Pressure Reactor -<idealgasconstpresreactor.html#ideal-gas-constant-pressure-reactor>`__ -allows the user to modify the governing equations corresponding to -the following state variables: - -- :math:`m`, the mass of the reactor's contents (in kg) - -- :math:`T`, the temperature (in K) - -- :math:`Y_k`, the mass fractions for each species (dimensionless) - -As shown in the derivations of the governing equations for an Ideal Gas -Constant Pressure Reactor, the user may modify the three equations below: - -.. math:: - - \frac{dm}{dt} = \sum_{in} \dot{m}_{in} - \sum_{out} \dot{m}_{out} + - \dot{m}_{wall} - \tag{1} - -.. math:: - - m c_p \frac{dT}{dt} = - \dot{Q} - \sum_k h_k \dot{m}_{k,gen} - + \sum_{in} \dot{m}_{in} \left(h_{in} - \sum_k h_k Y_{k,in} \right) - \tag{2} - -.. math:: - - m \frac{dY_k}{dt} = \sum_{in} \dot{m}_{in} (Y_{k,in} - Y_k)+ - \dot{m}_{k,gen} - Y_k \dot{m}_{wall} - \tag{3} - -There are two "sides" to each of these equations: the terms left of the equals -sign and the terms to the right of the equals sign. This is the format -in which the user will be editing the governing equations. For example, -if the user wishes to add a term for a large mass (say a rock) inside -the reactor to see the effects on temperature: - -.. math:: - - m c_p \frac{dT}{dt} = - \dot{Q} - \sum_k h_k \dot{m}_{k,gen} - + \sum_{in} \dot{m}_{in} \left(h_{in} - \sum_k h_k Y_{k,in} \right) - \tag{2} - -Will change to: - -.. math:: - - \left(m c_p + m_{rock} c_{p,rock}\right) \frac{dT}{dt} = - \dot{Q} - \sum_k h_k \dot{m}_{k,gen} - + \sum_{in} \dot{m}_{in} \left(h_{in} - \sum_k h_k Y_{k,in} \right) - -A simple example is shown below to illustrate the process for implementing -changes in Cantera's existing governing equations. -We will be replacing the right-hand side (RHS) and left-hand side (LHS) of -the temperature governing equation for an Ideal Gas Constant Pressure Reactor. -All other governing equations defining an Ideal Gas Constant Pressure Reactor -will remain as the default. - -In this example - -.. math:: - - m c_p \frac{dT}{dt} = - \dot{Q} - \sum_k h_k \dot{m}_{k,gen} - + \sum_{in} \dot{m}_{in} \left(h_{in} - \sum_k h_k Y_{k,in} \right) - \tag{2} - -Will change to: - -.. math:: - - \left( m_{rock} c_{p,rock} + m_{gas} \right) \frac{dT}{dt} = - \dot{Q} - -The governing equations will be modified through the user created Python class' methods. -For each method, the name should be prefixed with ``before_``, ``after_``, or -``replace_``, indicating whether the this method should be called before, after, -or instead of the corresponding method from the base class. - -.. code-block:: python - - #1 Define objects, properties, and initial conditions. - - #create gas object - gas = ct.Solution('h2o2.yaml') - gas.TPX = 500, ct.one_atm, 'H2:2,O2:1,N2:4' - - # define properties of gas and solid - mass_gas = 20 # [kg] - Q = 100 # [J/s] - mass_rock = 10 # [kg] - cp_rock = 1.0 # [J/kgK] - - #initialize time at zero - time = 0 # [s] - n_steps = 300 - - #2 Define a new custom Reactor class. Here we named it "RockReactor" and - # chose the Ideal Gas Constant Pressure Reactor as the base class to inherit - # governing equations from. - - # define a class representing reactor with a solid mass and gas inside of it - class RockReactor(ct.ExtensibleIdealGasConstPressureReactor): - - # modify energy equation to include solid mass in reactor - - # after the initial solution for time t is computed ask Cantera to solve the modified - # equation. The index 1 refers to modification of governing equation 2 in the reactor - # documentation (recall that indexing begins at 0). - def after_eval(self, t, LHS, RHS): - # although the time variable t is not used directly in the method definition it is a - # required argument for the internal solver. - self.m_mass = mass_gas - # as the arguments for after_eval are positional arguments, you may name them as you wish - # rather than use the default RHS and LHS nomenclature. - LHS[1] = mass_rock * cp_rock + self.m_mass * self.thermo.cp_mass - RHS[1] = -Q - - # Initialize the new Reactor class and Reactor Network. - r1 = RockReactor(gas) - r1_net = ct.ReactorNet([r1]) - - #3 Integrate custom equations over desired time. - - for n in range(n_steps): - time += 4.e-4 - r1_net.advance(time) - -The final state vector for your reactor network contains the final gas -properties obtained from Cantera using the modified equation(s). - -Details on functions in addition to ``eval()`` -that are able to be modified with ``before_``, ``after_``, or -``replace_`` can be found `here -<{{% ct_docs sphinx/html/cython/zerodim.html#extensiblereactor %}}>`__. - -More in-depth documentation on the different ways to modify equations using -an Extensible Reactor can be found `here <{{% ct_docs doxygen/html/de/d7e/classCantera_1_1ReactorDelegator.html %}}>`__ and `here -<{{% ct_docs sphinx/html/cython/zerodim.html#extensiblereactor %}}>`__. diff --git a/pages/science/reactors/idealgasconstpresmolereactor.rst b/pages/science/reactors/idealgasconstpresmolereactor.rst deleted file mode 100644 index fe203717c..000000000 --- a/pages/science/reactors/idealgasconstpresmolereactor.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. title: Ideal Gas Constant Pressure Mole Reactor -.. has_math: true - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Ideal Gas Constant Pressure - Mole Reactor</h1> - - .. class:: lead - - This page shows the derivation of the governing equations used in - Cantera's Ideal Gas Constant Pressure Mole Reactor model. - - More information on the Ideal Gas Constant Pressure Mole Reactor class can - be found `here. <{{% ct_docs doxygen/html/de/daa/classCantera_1_1IdealGasConstPressureMoleReactor.html %}}>`__ - -Ideal Gas Constant Pressure Reactor -*********************************** - -An Ideal Gas Constant Pressure Mole Reactor is defined by the two state variables: - -- :math:`T`, the temperature (in K) - -- :math:`n_k`, the number of moles for each species (in kmol) - -The energy equation in terms of temperature is necessary as we replaced enthalpy in the state vector with temperature. -We develop the equation for temperature by writing the total enthalpy in terms of the molar enthalpy and moles of each species. - -.. math:: - - H = \sum_k \bar{h}_k(T) n_k(T) - - \frac{dH}{dt} = \frac{dT}{dt}\sum_k n_k \bar{c_{p,k}} + \sum \bar{h}_k \dot{n}_k - -After some manipulations yields an equation for the -temperature: - -.. math:: - - \sum_k n_k \bar{c}_{p,k} \frac{dT}{dt} = \dot{Q} - \sum \bar{h}_k \dot{n}_k - \tag{1} - -The moles of each species in the reactor's contents changes as a result of flow through -the reactor's inlets and outlets, and production of homogeneous gas phase species and reactions on the reactor :py:class:`Wall`. -The rate of moles of species :math:`k` generated through homogeneous phase -reactions is :math:`V \dot{\omega}_k`, and the total rate at which moles of species -:math:`k` changes is: - -.. math:: - - \frac{dn_k}{dt} = V \dot{\omega}_k + \sum_{in} \dot{n}_{k, in} - \sum_{out} \dot{n}_{k, out} + \dot{n}_{k, wall} - \tag{2} - -Where the subscripts *in* and *out* refer to the sum of the corresponding property -over all inlets and outlets respectively. A dot above a variable signifies a time -derivative. Reactor *Walls* are defined `here. <{{% ct_docs sphinx/html/cython/zerodim.html#cantera.Wall %}}>`__ - - -Equations 1-2 are the governing equations for an Ideal Gas Constant Pressure -Mole Reactor. diff --git a/pages/science/reactors/idealgasconstpresreactor.rst b/pages/science/reactors/idealgasconstpresreactor.rst deleted file mode 100644 index f1d24c1fd..000000000 --- a/pages/science/reactors/idealgasconstpresreactor.rst +++ /dev/null @@ -1,89 +0,0 @@ -.. title: Ideal Gas Constant Pressure Reactor -.. has_math: true - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Ideal Gas Constant Pressure Reactor</h1> - - .. class:: lead - - This page shows the derivation of the governing equations used in - Cantera's Ideal Gas Constant Pressure Reactor model. - - More information on the Ideal Gas Constant Pressure Reactor class can - be found `here. <{{% ct_docs doxygen/html/dc/d5d/classCantera_1_1IdealGasConstPressureReactor.html %}}>`__ - -Ideal Gas Constant Pressure Reactor -*********************************** - -An Ideal Gas Constant Pressure Reactor is defined by the three state variables: - -- :math:`m`, the mass of the reactor's contents (in kg) - -- :math:`T`, the temperature (in K) - -- :math:`Y_k`, the mass fractions for each species (dimensionless) - -The total mass of the reactor's contents changes as a result of flow through -the reactor's inlets and outlets, and production of homogeneous phase species -on :py:class:`ReactorSurface` objects: - -.. math:: - - \frac{dm}{dt} = \sum_{in} \dot{m}_{in} - \sum_{out} \dot{m}_{out} + - \dot{m}_{wall} - \tag{1} - -Where the subscripts *in* and *out* refer to the sum of the superscipted property -over all inlets and outlets respectively. A dot above a variable signifies a time -derivative. - -As for the Ideal Gas Reactor, we replace the total enthalpy as a state -variable with the temperature by writing the total enthalpy in terms of the -mass fractions and temperature: - -.. math:: - - H = m \sum_k Y_k h_k(T) - - \frac{dH}{dt} = h \frac{dm}{dt} + m c_p \frac{dT}{dt} - + m \sum_k h_k \frac{dY_k}{dt} - -Substituting the corresponding derivatives yields an equation for the -temperature: - -.. math:: - - m c_p \frac{dT}{dt} = \dot{Q} - \sum_k h_k \dot{m}_{k,gen} - + \sum_{in} \dot{m}_{in} \left(h_{in} - \sum_k h_k Y_{k,in} \right) - \tag{2} - -The rate at which species :math:`k` is generated through homogeneous phase -reactions is :math:`V \dot{\omega}_k W_k`, and the total rate at which species -:math:`k` is generated is: - -.. math:: - - \dot{m}_{k,gen} = V \dot{\omega}_k W_k + \dot{m}_{k,wall} - -The rate of change in the mass of each species is: - -.. math:: - - \frac{d(mY_k)}{dt} = \sum_{in} \dot{m}_{in} Y_{k,in} - - \sum_{out} \dot{m}_{out} Y_k + - \dot{m}_{k,gen} - -Expanding the derivative on the left hand side and substituting the equation -for :math:`dm/dt`, the equation for each homogeneous phase species is: - -.. math:: - - m \frac{dY_k}{dt} = \sum_{in} \dot{m}_{in} (Y_{k,in} - Y_k)+ - \dot{m}_{k,gen} - Y_k \dot{m}_{wall} - \tag{3} - -Equations 1-3 are the governing equations for an Ideal Gas Constant Pressure -Reactor. \ No newline at end of file diff --git a/pages/science/reactors/idealgasmolereactor.rst b/pages/science/reactors/idealgasmolereactor.rst deleted file mode 100644 index ef9e242a5..000000000 --- a/pages/science/reactors/idealgasmolereactor.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. title: Ideal Gas Mole Reactor -.. has_math: true - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Ideal Gas Mole Reactor</h1> - - .. class:: lead - - This page shows the derivation of the governing equations used in - Cantera's Ideal Gas Mole Reactor model. - - More information on the Ideal Gas Mole Reactor class can be found `here. - <{{% ct_docs doxygen/html/d0/d03/classCantera_1_1IdealGasMoleReactor.html %}}>`__ - -Ideal Gas Mole Reactor -********************** - -An Ideal Gas Mole Reactor is defined by the three state variables: - -- :math:`T`, the temperature (in K) - -- :math:`V`, the reactor volume (in m\ :sup:`3`) - -- :math:`n_k`, the number of moles for each species (in kmol) - -The energy equation in terms of temperature is necessary as we replaced internal energy in the state vector with temperature. -We develop the equation for temperature by writing the total enthalpy in terms of the molar enthalpy and moles of each species. - -.. math:: - - U = \sum_k \bar{u}_k(T) n_k(T) - - \frac{dU}{dt} = \frac{dT}{dt}\sum_k n_k \bar{c_{v,k}} + \sum \bar{u}_k \dot{n}_k - -After some manipulations yields an equation for the -temperature: - -.. math:: - - \frac{dT}{dt} = \frac{\dot{Q} - \sum \bar{u}_k \dot{n}_k}{\sum_k n_k \bar{c}_{p,k} } - \tag{1} - -The reactor volume changes as a function of time due to the motion of one or -more walls: - -.. math:: - - \frac{dV}{dt} = \sum_w f_w A_w v_w(t) - \tag{2} - -Where :math:`f_w = \pm 1` indicates the facing of the wall (whether moving the wall increases or decreases the volume of the reactor), :math:`A_w` is the surface area of the wall, and :math:`v_w(t)` is the velocity of the wall as a function of time. - -Finally, the moles of each species in the reactor's contents changes as a result of flow through the reactor's inlets and outlets, and production of homogeneous gas phase species and reactions on the reactor :py:class:`Wall`. -The rate of moles of species :math:`k` generated through homogeneous phase -reactions is :math:`V \dot{\omega}_k`, and the total rate at which moles of species -:math:`k` changes is: - -.. math:: - - \frac{dn_k}{dt} = V \dot{\omega}_k + \sum_{in} \dot{n}_{k, in} - \sum_{out} \dot{n}_{k, out} + \dot{n}_{k, wall} - \tag{3} - -Equations 1-3 are the governing equations for an Ideal Gas Mole Reactor. diff --git a/pages/science/reactors/idealgasreactor.rst b/pages/science/reactors/idealgasreactor.rst deleted file mode 100644 index 3c1467ef1..000000000 --- a/pages/science/reactors/idealgasreactor.rst +++ /dev/null @@ -1,110 +0,0 @@ -.. title: Ideal Gas Reactor -.. has_math: true - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Ideal Gas Reactor</h1> - .. class:: lead - - This page shows the derivation of the governing equations used in - Cantera's Ideal Gas Reactor model. - - More information on the Ideal Gas Reactor class can be found `here. - <{{% ct_docs doxygen/html/dc/d06/classCantera_1_1IdealGasReactor.html %}}>`__ - -Ideal Gas Reactor -***************** - -An Ideal Gas Reactor is defined by the four state variables: - -- :math:`m`, the mass of the reactor's contents (in kg) - -- :math:`V`, the reactor volume (in m\ :sup:`3`) - -- :math:`T`, the temperature (in K) - -- :math:`Y_k`, the mass fractions for each species (dimensionless) - -The total mass of the reactor's contents changes as a result of flow through -the reactor's inlets and outlets, and production of homogeneous phase species -on :py:class:`ReactorSurface` objects: - -.. math:: - - \frac{dm}{dt} = \sum_{in} \dot{m}_{in} - \sum_{out} \dot{m}_{out} + - \dot{m}_{wall} - \tag{1} - -Where the subscripts *in* and *out* refer to the sum of the corresponding property -over all inlets and outlets respectively. A dot above a variable signifies a time -derivative. - -The reactor volume changes as a function of time due to the motion of one or -more :py:class:`Wall` objects: - -.. math:: - - \frac{dV}{dt} = \sum_w f_w A_w v_w(t) - \tag{2} - -Where :math:`f_w = \pm 1` indicates the facing of the wall (whether moving the wall increases or -decreases the volume of the reactor), :math:`A_w` is the -surface area of the wall, and :math:`v_w(t)` is the velocity of the wall as a -function of time. - -In case of the Ideal Gas Reactor Model, the reactor temperature :math:`T` is -used instead of the total internal energy :math:`U` as a state variable. For an -ideal gas, we can rewrite the total internal energy in terms of the mass -fractions and temperature: - -.. math:: - - U = m \sum_k Y_k u_k(T) - - \frac{dU}{dt} = u \frac{dm}{dt} - + m c_v \frac{dT}{dt} - + m \sum_k u_k \frac{dY_k}{dt} - -Substituting the corresponding derivatives yields an equation for the -temperature: - -.. math:: - - m c_v \frac{dT}{dt} = - p \frac{dV}{dt} + \dot{Q} - + \sum_{in} \dot{m}_{in} \left( h_{in} - \sum_k u_k Y_{k,in} \right) - - \frac{p V}{m} \sum_{out} \dot{m}_{out} - \sum_k \dot{m}_{k,gen} u_k - \tag{3} - -While this form of the energy equation is somewhat more complicated, it -significantly reduces the cost of evaluating the system Jacobian, since the -derivatives of the species equations are taken at constant temperature instead -of constant internal energy. - -The rate at which species :math:`k` is generated through homogeneous phase -reactions is :math:`V \dot{\omega}_k W_k`, and the total rate at which species -:math:`k` is generated is: - -.. math:: - - \dot{m}_{k,gen} = V \dot{\omega}_k W_k + \dot{m}_{k,wall} - -The rate of change in the mass of each species is: - -.. math:: - - \frac{d(mY_k)}{dt} = \sum_{in} \dot{m}_{in} Y_{k,in} - - \sum_{out} \dot{m}_{out} Y_k + - \dot{m}_{k,gen} - -Expanding the derivative on the left hand side and substituting the equation -for :math:`dm/dt`, the equation for each homogeneous phase species is: - -.. math:: - - m \frac{dY_k}{dt} = \sum_{in} \dot{m}_{in} (Y_{k,in} - Y_k)+ - \dot{m}_{k,gen} - Y_k \dot{m}_{wall} - \tag{4} - -Equations 1-4 are the governing equations for an Ideal Gas Reactor. \ No newline at end of file diff --git a/pages/science/reactors/molereactor.rst b/pages/science/reactors/molereactor.rst deleted file mode 100644 index 980538a92..000000000 --- a/pages/science/reactors/molereactor.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. title: Mole Reactor -.. has_math: true - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Mole Reactor</h1> - - .. class:: lead - - This page shows the derivation of the governing equations used in - Cantera's Mole Reactor model. - - More information on the Mole Reactor class can be found `here. - <{{% ct_docs doxygen/html/da/d29/classCantera_1_1MoleReactor.html %}}>`__ - -Mole Reactor -************ - -A homogeneous zero-dimensional reactor. By default, they are closed (no inlets or outlets), -have fixed volume, and have adiabatic, chemically-inert walls. These properties may all be -changed by adding appropriate components such as :py:class:`Wall`, :py:class:`ReactorSurface`, -:py:class:`MassFlowController`, and :py:class:`Valve`. - -A Mole Reactor is defined by the three state variables: - -- :math:`U`, the total internal energy of the reactor's contents (in J) - -- :math:`V`, the reactor volume (in m\ :sup:`3`) - -- :math:`n_k`, the number of moles for each species (in kmol) - -The equation for the total internal energy is found by writing the first law -for an open system: - -.. math:: - - \frac{dU}{dt} = - p \frac{dV}{dt} + \dot{Q} + - \sum_{in} \dot{n}_{in} \bar{h}_{in} - \bar{h} \sum_{out} \dot{n}_{out} - \tag{1} - -Where :math:`\dot{Q}` is the net rate of heat addition to the system. - -The reactor volume changes as a function of time due to the motion of one or -more :py:class:`Wall`\ s: - -.. math:: - - \frac{dV}{dt} = \sum_w f_w A_w v_w(t) - \tag{2} - -where :math:`f_w = \pm 1` indicates the facing of the wall (whether moving the wall increases or -decreases the volume of the reactor), :math:`A_w` is the -surface area of the wall, and :math:`v_w(t)` is the velocity of the wall as a -function of time. - -The moles of each species in the reactor's contents changes as a result of flow through -the reactor's inlets and outlets, and production of homogeneous gas phase species and reactions on the reactor :py:class:`Wall`. -The rate of moles of species :math:`k` generated through homogeneous phase -reactions is :math:`V \dot{\omega}_k`, and the total rate at which moles of species -:math:`k` changes is: - -.. math:: - - \frac{dn_k}{dt} = V \dot{\omega}_k + \sum_{in} \dot{n}_{k, in} - \sum_{out} \dot{n}_{k, out} + \dot{n}_{k, wall} - \tag{3} - -Where the subscripts *in* and *out* refer to the sum of the corresponding property -over all inlets and outlets respectively. A dot above a variable signifies a time -derivative. - -Equations 1-3 are the governing equations for a Mole Reactor. diff --git a/pages/science/reactors/pfr.rst b/pages/science/reactors/pfr.rst deleted file mode 100644 index b9464828e..000000000 --- a/pages/science/reactors/pfr.rst +++ /dev/null @@ -1,149 +0,0 @@ -.. title: Plug Flow Reactor -.. has_math: true - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Plug Flow Reactor</h1> - - .. class:: lead - - This page shows the derivation of the governing equations used in - Cantera's Plug Flow Reactor model. - -Plug Flow Reactor -***************** - -A Plug Flow Reactor (PFR) represents a steady-state flow in a channel. Perpendicular to -the flow direction, the gas is considered to be completely homogeneous. In the axial -direction :math:`z`, the state of the gas is allowed to change. However, all diffusion -processes are neglected. - -In addition, the interior surface of the reactor may consist of one or more -catalytically active surfaces where heterogenous reactions occur. - -Plug-Flow Reactors are often used to simulate emission formation and catalytic processes. - -A Plug Flow Reactor is defined by the state variables: - -- :math:`\rho`, the density of the fluid phase (in kg/m\ :sup:`3`) - -- :math:`u`, the velocity of the fluid phase (in m/s) - -- :math:`p`, the pressure (in Pa) - -- :math:`T`, the temperature (in K) - -- :math:`Y_k`, the mass fractions for each fluid phase species (dimensionless) - -- :math:`\theta_{i,j}`, the coverage of each surface species :math:`i` on each surface - :math:`j` (dimensionless) - -The reactor geometry is defined by the length :math:`L`, total volume :math:`V`, and the -surface area :math:`A_{s,j}` for each surface, where the surface area per unit length is -assumed to be a constant along the length of the reactor. - -The governing equations for a PFR are a system of differential-algebraic equations, -which depend on the spatial derivatives of some but not all of the state variables. The -plug flow reactor model in Cantera is implemented by class `FlowReactor <{{% ct_docs -doxygen/html/da/dae/classCantera_1_1FlowReactor.html %}}>`__. - - -*Equation of state* - -The fluid satisfies the ideal gas law: - -.. math:: - - \rho = \frac{p \overline{W}}{R T} - -where :math:`R` is the universal gas constant and :math:`\overline{W}` is the mixture -molecular weight. - -*Mass conservation:* - -The net rate at which fluid phase species are generated by reactions on the walls (per -unit cross sectional area) can be defined as - -.. math:: - - \dot{m}_s = \sum_j \frac{A_{s,j}}{V} \left(\sum_k \dot{s}_{k,j} W_k\right) - -where :math:`\dot{s}_{k,j}` is the net rate of production of species :math:`k` on -surface :math:`j` and :math:`W_k` is the molecular weight of species :math:`k`. The -overall mass conservation equation for the reactor can then be written as: - -.. math:: - - u \frac{d\rho}{dz} + \rho \frac{du}{dz} = \dot{m}_s - \tag{1} - -*Momentum conservation in the axial direction:* - -.. math:: - - \rho u \frac{du}{dz} = - u \dot{m}_s - \frac{dp}{dz} - \tag{2} - -*Energy conservation:* - -.. math:: - - \rho u c_p \frac{dT}{dz} = - - \sum_k \hat{h}_k \dot{\omega}_k - - \sum_j \frac{A_{s,j}}{V} \left(\sum_k \hat{h}_k \dot{s}_{k,j}\right) - \tag{3} - -where :math:`c_p` is the specific heat capacity of the mixture and :math:`\hat{h}_k` is -the molar enthalpy of species :math:`k`. Kinetic and potential energies are neglected. - -*Conservation equation for fluid species* :math:`k`: - -.. math:: - - \rho u \frac{d Y_k}{dz} = - Y_k \dot{m}_s - + \dot{\omega}_k W_k + \sum_j \frac{A_{s,j}}{V} \dot{s}_k W_k - \tag{4} - - -*Conservation equation for surface species* :math:`i,j`: - -Because the PFR is modeled as steady state, net rate of production for each surface -species must be zero. To satisfy the constraint that the total surface coverage is 1, -the conservation equation for the first surface species on each surface is replaced -by this constraint: - -.. math:: - - \dot{s}_{i,j} = 0,\quad i \ne 0 - \tag{5} - - \dot{s}_{0,j} = 1 - \sum_{i\ne 0} \theta_{i,j} - \tag{6} - -Integrating the PFR -------------------- - -Because diffusion is neglected, downstream parts of the reactor have no influence on -upstream parts. Therefore, PFRs can be integrated as initial value problems, starting -from the composition at the inlet. Some care is required to determine initial values for -the algebraic variables (the surface species coverages) and the time derivatives for the -differential variables (the other state variables) that are consistent with the -governing equations. - -To do this, we first solve the steady-state problem for each surface, holding the fluid -phase composition, temperature, and pressure fixed at the inlet values to determine the -values of :math:`\theta_{i,j}(z=0)`. Then, we construct a linear system comprising the -ideal gas law, differentiated with respect to :math:`z` and equations (1), (2), (3), and -(4) evaluated at :math:`z=0`. This system is then solved to obtain the values of -:math:`d\rho/dz`, :math:`du/dz`, :math:`dp/dz`, :math:`dT/dz`, and :math:`dY_k/dz` at -:math:`z=0`. - -Examples --------- - -- `Partial oxidation of methane over a platinum catalyst - </examples/python/reactors/surf_pfr.py.html>`__ -- `silicon nitride (Si3N4) deposition from ammonia (NH3) and silicon tetrafluoride - (SiF4) </examples/python/surface_chemistry/1D_pfr_surfchem.py.html>`__ diff --git a/pages/science/reactors/reactors.rst b/pages/science/reactors/reactors.rst deleted file mode 100644 index 549b24f8f..000000000 --- a/pages/science/reactors/reactors.rst +++ /dev/null @@ -1,658 +0,0 @@ -.. slug: reactors -.. title: Reactor Models in Cantera -.. has_math: true - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Reactors and Reactor Networks</h1> - - .. class:: lead - - Cantera Reactors and Reactor Networks model zero-dimensional reactors and their - interactions with the surroundings. - -Reactors -======== - -A Cantera :py:class:`Reactor` represents the simplest form of a chemically reacting system. It -corresponds to an extensive thermodynamic control volume :math:`V`, in which all state variables are -homogeneously distributed. The system is generally unsteady -- that is, all states are functions of time. -In particular, transient state changes due to chemical reactions are possible. However, -thermodynamic (but not chemical) equilibrium is assumed to be present throughout the reactor at all -instants of time. - -Reactors can interact with the surrounding environment in multiple ways: - -- Expansion/compression work: By moving the walls of the reactor, its volume can be changed and - expansion or compression work can be done by or on the reactor. - -- Heat transfer: An arbitrary heat transfer rate can be defined to cross the boundaries of the - reactor. - -- Mass transfer: The reactor can have multiple inlets and outlets. For the inlets, arbitrary states - can be defined. Fluid with the current state of the reactor exits the reactor at the outlets. - -- Surface interaction: One or multiple walls can influence the chemical reactions in the reactor. - This is not just restricted to catalytic reactions, but mass transfer between the surface and the - fluid can also be modeled. - -All of these interactions do not have to be constant, but can vary as a function of time or state. -For example, heat transfer can be described as a function of the temperature difference between the -reactor and the environment, or the wall movement can be modeled depending on the pressure -difference. Interactions of the reactor with the environment are defined on one or more *walls*, -*inlets*, and *outlets*. - -In addition to single reactors, Cantera is also able to interconnect reactors into a Reactor -Network. Each reactor in a network may be connected so that the contents of one reactor flow into -another. Reactors may also be in contact with one another or the environment via walls that conduct -heat or move to do work. - -Reactor Types and Governing Equations -===================================== - -All reactor types are modelled using combinations of Cantera's governing equations of state. -The specific governing equations defining Cantera's supported reactor models are derived and described below. - -.. container:: container - - .. row:: - - .. container:: col-12 - - .. container:: card-deck - - .. container:: card - - .. container:: - :tagname: a - :attributes: href="controlreactor.html" - title="Control Volume Reactor" - - .. container:: card-header section-card - - Control Volume Reactor - - .. - - - .. container:: card-body - - .. container:: card-text - - A reactor where the volume is prescribed by the motion of the - reactor's walls. The state variables are the volume, mass, total - internal energy, and species mass fractions. - - .. container:: card - - .. container:: - :tagname: a - :attributes: href="constpresreactor.html" - title="Constant Pressure Reactor" - - .. container:: card-header section-card - - Constant Pressure Reactor - - .. container:: card-body - - .. container:: card-text - - A reactor where the pressure is held constant by varying the volume. - The state variables are the mass, total enthalpy, and species mass - fractions. - - .. container:: card - - .. container:: - :tagname: a - :attributes: href="idealgasreactor.html" - title="Ideal Gas Reactor" - - .. container:: card-header section-card - - Ideal Gas Reactor - - .. container:: card-body - - .. container:: card-text - - A reactor where the volume is prescribed by the - motion of the reactor's walls, specialized for ideal gas mixtures. - The state variables are the mass, volume, temperature, and species - mass fractions. - -.. container:: container - - .. row:: - - .. container:: col-12 - - .. container:: card-deck - - .. container:: card - - .. container:: - :tagname: a - :attributes: href="idealgasconstpresreactor.html" - title="Ideal Gas Constant Pressure Reactor" - - .. container:: card-header section-card - - Ideal Gas Constant Pressure Reactor - - .. container:: card-body - - .. container:: card-text - - A reactor where the pressure is held constant by varying the volume, - specialized for ideal gas mixtures. The state variables are the - mass, temperature, and species mass fractions. - - .. container:: card - - .. container:: - :tagname: a - :attributes: href="pfr.html" - title="Plug Flow Reactor" - - .. container:: card-header section-card - - Plug Flow Reactor - - .. container:: card-body - - .. container:: card-text - - A steady-state reactor channel with an ideal gas flowing through it - and heterogeneous reactions occurring on the walls. - - -A set of reactors with a mole-based state vector are implemented to leverage -preconditioning techniques which do not have the same applicability to traditional mass -fraction based solutions. More on preconditioning can be found in description of the -SUNDIALS time integration `here. <cvodes.html>`__ -The primary difference in "Mole reactors" is that the governing equations are derived in -terms of the moles of each species instead of total mass and the mass fractions. - - -.. container:: container - - .. row:: - - .. container:: col-12 - - .. container:: card-deck - - .. container:: card - - .. container:: - :tagname: a - :attributes: href="molereactor.html" - title="Mole Reactor" - - .. container:: card-header section-card - - Mole Reactor - - .. container:: card-body - - .. container:: card-text - - A control volume reactor where the state variables are the volume, - total internal energy, and moles of each species. - - - .. container:: card - - .. container:: - :tagname: a - :attributes: href="constpresmolereactor.html" - title="Constant Pressure Mole Reactor" - - .. container:: card-header section-card - - Constant Pressure Mole Reactor - - .. - - .. container:: card-body - - .. container:: card-text - - A constant pressure reactor where the state variables are the - total enthalpy and the moles of each species. - - .. row:: - - .. container:: col-12 - - .. container:: card-deck - - .. container:: card - - .. container:: - :tagname: a - :attributes: href="idealgasmolereactor.html" - title="Ideal Gas Mole Reactor" - - .. container:: card-header section-card - - Ideal Gas Mole Reactor - - .. container:: card-body - - .. container:: card-text - - A control volume reactor specialized for ideal gases, where the - state variables are the volume, temperature, and the moles of each - species. - - - .. container:: card - - .. container:: - :tagname: a - :attributes: href="idealgasconstpresmolereactor.html" - title="Ideal Gas Constant Pressure Mole Reactor" - - .. container:: card-header section-card - - Ideal Gas Constant Pressure Mole Reactor - - .. container:: card-body - - .. container:: card-text - - A constant pressure reactor specialized for ideal gases, where the - state variables are the temperature and the moles of each species. - -Extensible Reactors -------------------- - -In some cases, Cantera's built-in reactor types are insufficient to model a problem. -In this situation, the ``ExtensibleReactor`` family of classes can be used to modify -and governing equations, starting from one of the built-in reactor types. - -These reactor types allow the methods that implement the governing equations and related -reactor configuration to be augmented or replaced with user-defined Python functions. -New state variables can be added to the reactor, and existing ones can be redefined. -User-defined ``ExtensibleReactor`` implementations can be used alongside the built-in -reactor types to build reactor networks that can be integrated using the ``ReactorNet`` -integrator provided by Cantera. - -Several examples demonstrating the use of ``ExtensibleReactor`` classes are given below. -Detailed API documentation can be found with the Python :py:class:`ExtensibleReactor` -class. - -.. container:: container - - .. row:: - - .. container:: col-12 - - .. container:: card-deck - - .. container:: card - - .. container:: - :tagname: a - :attributes: href="extensiblereactor.html" - title="Extensible Reactor Tutorial" - - .. container:: card-header section-card - - Extensible Reactor Tutorial - - .. container:: card-body - - .. container:: card-text - - A simple example of an ``ExtensibleReactor`` that walks through - the definition of modified governing equations and shows how to - define the Python methods that implement these changes to the - equations. - - .. container:: card - - .. container:: - :tagname: a - :attributes: href="../../examples/python/reactors/custom2.py.html" - title="Adding New State Variables" - - .. container:: card-header section-card - - Adding New State Variables - - .. container:: card-body - - .. container:: card-text - - An example that shows how to add a new state variable to an - ``ExtensibleReactor``, in order to implement a reactor where an - adjacent wall has inertia and takes time to respond to changes in - the reactor's pressure. - - .. container:: card - - .. container:: - :tagname: a - :attributes: href="../../examples/python/reactors/PorousMediaBurner.py.html" - title="Complex Reactor Interactions" - - .. container:: card-header section-card - - Complex Reactor Interactions - - .. container:: card-body - - .. container:: card-text - - An example that implements fully-customized governing equations - to implement a porous media burner, with several new forms of - interaction between adjacent reactors. - - -Reactor Networks -================ - -While reactors by themselves just define the above governing equations of the -reactor, the time integration is performed in reactor networks. In other words -defining a reactor without assigning it to a reactor network prevents Cantera -from performing time integration to solve the governing equations. A reactor -network is therefore necessary to define even if only a single reactor is considered. -An example of a single reactor network can be found `here -</examples/python/reactors/combustor.py.html>`__. - -.. container:: container - - .. row:: - - .. container:: col-12 - - .. container:: card-deck - - .. container:: card - - .. container:: - :tagname: a - :attributes: href="cvodes.html" - title="CVODES" - - .. container:: card-header section-card - - Time Integration for Reactor Networks: CVODES - - .. - - - .. container:: card-body - - .. container:: card-text - - Cantera uses the CVODES solver from the `SUNDIALS - <https://computing.llnl.gov/projects/sundials>`__ - package to integrate the stiff ODEs of reacting systems. These stiff ODEs are referring to - the governing equations defining the reactors above. - More in-depth information on the CVODES solver can be found here. - -Reactor Peripherals -=================== - -Reactor networks are also how Cantera interconnects multiple reactors. Not -only mass flow from one reactor into another can be incorporated, but also heat -can be transferred, or the wall between reactors can move. Documentation -on the different ways to connect reactors is explained here. - -To set up a network, the following components can be defined in addition -to the reactors previously mentioned: - -- :py:class:`Reservoir`: A reservoir can be thought of as an infinitely large volume, in - which all states are predefined and never change from their initial values. - Typically, it represents a vessel to define temperature and composition of a - stream of mass flowing into a reactor, or the ambient fluid surrounding the - reactor network. Besides, the fluid flow finally exiting a reactor - network has to flow into a reservoir. In the latter case, the state of the - reservoir (except pressure) is irrelevant. - -- :py:class:`Wall`: A wall separates two reactors, or a reactor and a reservoir. A wall - has a finite area, may conduct or radiate heat between the two reactors on - either side, and may move like a piston. See the `Wall Interactions`_ section below for - detail of how the wall affects the connected reactors. - -- :py:class:`Valve`: A valve is a flow devices with mass flow rate that is a function of - the pressure drop across it. The mass flow rate is computed as: - - .. math:: - - \dot m = K_v g(t) f(P_1 - P_2) - - with :math:`K_v` being a proportionality constant that is set using the class - property :py:func:`Valve.valve_coeff`. Further, :math:`g` and :math:`f` - are functions of time and pressure drop that are set by class methods - :py:func:`Valve.set_time_function` and :py:func:`Valve.set_pressure_function`, - respectively. If no functions are specified, the mass flow rate defaults to: - - .. math:: - - \dot m = K_v (P_1 - P_2) - - The pressure difference between upstream (*1*) and downstream (*2*) reservoir - is defined as :math:`P_1 - P_2`. It is never possible for the flow to reverse - and go from the downstream to the upstream reactor/reservoir through a line - containing a :py:class:`Valve` object, which means that the flow rate is set to zero if - :math:`P_1 < P_2`. - - :py:class:`Valve` objects are often used between an upstream reactor and a downstream - reactor or reservoir to maintain them both at nearly the same pressure. By - setting the constant :math:`K_v` to a sufficiently large value, very small - pressure differences will result in flow between the reactors that counteracts - the pressure difference. - -- :py:class:`MassFlowController`: A mass flow controller maintains a specified mass - flow rate independent of upstream and downstream conditions. The equation used - to compute the mass flow rate is - - .. math:: - - \dot m = m_0 g(t) - - where :math:`m_0` is a mass flow coefficient and :math:`g` is a function of time - which are set by class property :py:func:`MassFlowController.mass_flow_coeff` - and method :py:func:`MassFlowController.set_time_function`, respectively. If no - function is specified, the mass flow rate defaults to: - - .. math:: - - \dot m = m_0 - - Note that if :math:`\dot m < 0`, the mass flow rate will be set to zero, - since a reversal of the flow direction is not allowed. - - Unlike a real mass flow controller, a :py:class:`MassFlowController` object will maintain - the flow even if the downstream pressure is greater than the upstream - pressure. This allows simple implementation of loops, in which exhaust gas - from a reactor is fed back into it through an inlet. But note that this - capability should be used with caution, since no account is taken of the work - required to do this. - -- :py:class:`PressureController`: A pressure controller is designed to be used in - conjunction with another 'master' flow controller, typically a - :py:class:`MassFlowController`. The master flow controller is installed on the inlet of - the reactor, and the corresponding :py:class:`PressureController` is installed on on - outlet of the reactor. The :py:class:`PressureController` mass flow rate is equal to the - master mass flow rate, plus a small correction dependent on the pressure - difference: - - .. math:: - - \dot m = \dot m_{\text{master}} + K_v f(P_1 - P_2) - - where :math:`K_v` is a proportionality constant and :math:`f` is a function of - pressure drop :math:`P_1 - P_2` that are set by class property - :py:func:`PressureController.pressure_coeff` and method - :py:func:`PressureController.set_pressure_function`, respectively. If no - function is specified, the mass flow rate defaults to: - - .. math:: - - \dot m = \dot m_{\text{master}} + K_v (P_1 - P_2) - - Note that if :math:`\dot m < 0`, the mass flow rate will be set to zero, - since a reversal of the flow direction is not allowed. - - Cantera comes with a broad variety of well-commented example scrips for reactor - networks. Please see the `Cantera Examples </examples/index.html>`__ for further - information. - -Wall Interactions ------------------ - -Walls are stateless objects in Cantera, meaning that no differential equation -is integrated to determine any wall property. Since it is the wall (piston) -velocity that enters the energy equation, this means that it is the velocity, -not the acceleration or displacement, that is specified. The wall velocity is -computed from - -.. math:: - - v = K(P_{\mathrm{left}} - P_{\mathrm{right}}) + v_0(t), - -where :math:`K` is a non-negative constant, and :math:`v_0(t)` is a specified -function of time. The velocity is positive if the wall is moving to the right. - -The total rate of heat transfer through all walls is: - -.. math:: - - \dot{Q} = \sum_w f_w \dot{Q}_w - -where :math:`f_w = \pm 1` indicates the facing of the wall (-1 for the reactor -on the left, +1 for the reactor on the right). The heat flux :math:`\dot{Q}_w` -through a wall :math:`w` connecting reactors "left" and "right" is computed as: - -.. math:: - - \dot{Q}_w = U A (T_{\mathrm{left}} - T_{\mathrm{right}}) - + \epsilon\sigma A (T_{\mathrm{left}}^4 - T_{\mathrm{right}}^4) - + A q_0(t) - -where :math:`U` is a user-specified heat transfer coefficient (W/m\ :sup:`2`-K), -:math:`A` is the wall area (m\ :sup:`2`), :math:`\epsilon` is the user-specified -emissivity, :math:`\sigma` is the Stefan-Boltzmann radiation constant, and -:math:`q_0(t)` is a user-specified, time-dependent heat flux (W/m\ :sup:`2`). -This definition is such that positive :math:`q_0(t)` implies heat transfer from -the "left" reactor to the "right" reactor. Each of the user-specified terms -defaults to 0. - -In case of surface reactions, there can be a net generation (or destruction) of -homogeneous (gas) phase species at the wall. The molar rate of production for -each homogeneous phase species :math:`k` on wall :math:`w` is -:math:`\dot{s}_{k,w}` (in kmol/s/m\ :sup:`2`). The total (mass) production rate -for homogeneous phase species :math:`k` on all walls is: - -.. math:: - - \dot{m}_{k,wall} = W_k \sum_w A_w \dot{s}_{k,w} - -where :math:`W_k` is the molecular weight of species :math:`k` and :math:`A_w` -is the area of each wall. The net mass flux from all walls is then: - -.. math:: - - \dot{m}_{wall} = \sum_k \dot{m}_{k,wall} - -For each surface species :math:`i`, the rate of change of the site fraction -:math:`\theta_{i,w}` on each wall :math:`w` is integrated with time: - -.. math:: - - \frac{d\theta_{i,w}}{dt} = \frac{\dot{s}_{i,w} \sigma_i}{\Gamma_w} - -where :math:`\Gamma_w` is the total surface site density on wall :math:`w` and -:math:`\sigma_i` is the number of surface sites occupied by a molecule of species -:math:`i` (sometimes referred to within Cantera as the molecule's "size"). - -In the case of mole based reactors, -:math:`\dot{n}_{wall}` is needed which is calculated as: - -.. math:: - - \dot{n}_{k, wall} = A_{w}\sum_{w}\dot{s}_{w, k} - -Common Reactor Types and their Implementation in Cantera -======================================================== - -Batch Reactor at Constant Volume or at Constant Pressure --------------------------------------------------------- - -If you are interested in how a homogeneous chemical composition changes in time -when it is left to its own devices, a simple batch reactor can be used. Two versions -are commonly considered: A rigid vessel with fixed volume but variable -pressure, or a system idealized at constant pressure but varying volume. - -In Cantera, such a simulation can be performed very easily. The initial state -of the solution can be specified by composition and a set of thermodynamic -parameters (like temperature and pressure) as a standard Cantera solution -object. Upon its base, a general (Ideal Gas) Reactor or an (Ideal Gas) Constant -Pressure Reactor can be created, depending on if a constant volume or constant -pressure batch reactor should be considered, respectively. The behavior of the -solution in time can be simulated as a very simple Reactor Network containing -only the formerly created reactor. - -An example for such a Batch Reactor is given in the `examples -</examples/python/reactors/reactor1.py.html>`__. - -Continuously Stirred Tank Reactor ---------------------------------- - -A Continuously Stirred Tank Reactor (CSTR), also often referred to as -Well-Stirred Reactor (WSR), Perfectly Stirred Reactor (PSR), or Longwell -Reactor, is essentially a single Cantera reactor with an inlet, an outlet, and -constant volume. Therefore, the governing equations for single reactors -defined above apply accordingly. - -Steady state solutions to CSTRs are often of interest. In this case, the mass -flow rate :math:`\dot{m}` is constant and equal at inlet and outlet. The mass -contained in the confinement :math:`m` divided by :math:`\dot{m}` defines the mean -residence time of the fluid in the confinement. - -At steady state, the time derivatives in the governing equations become zero, -and the system of ordinary differential equations can be reduced to a set of -coupled nonlinear algebraic equations. A Newton solver could be used to solve -this system of equations. However, a sophisticated implementation might be -required to account for the strong nonlinearities and the presence of multiple -solutions. - -Cantera does not have such a Newton solver implemented. Instead, steady CSTRs -are simulated by considering a time-dependent constant volume reactor with -specified in- and outflow conditions. Starting off at an initial solution, the -reactor network containing this reactor is advanced in time until the state of -the solution is converged. An example for this procedure is -`the combustor example </examples/python/reactors/combustor.py.html>`__. - -A problem can be the ignition of a CSTR: If the reactants are not reactive -enough, the simulation can result in the trivial solution that inflow and -outflow states are identical. To solve this problem, the reactor can be -initialized with a high temperature and/or radical concentration. A good -approach is to use the equilibrium composition of the reactants (which can be -computed using Cantera's ``equilibrate`` function) as an initial guess. - -*Cantera always solves a transient problem. If you are interested in steady-state -conditions, you can run your simulation for a long time until the states are converged (see the* -`surface reactor example </examples/python/reactors/surf_pfr.py.html>`__ *and the* `combustor example -</examples/python/reactors/combustor.html>`__ *).* - -.. rubric:: For even more information on reactor equations, check out this reference: - -.. [Kee2017] R. J. Kee, M. E. Coltrin, P. Glarborg, and H. Zhu. *Chemically Reacting Flow: - Theory and Practice*. 2nd Ed. John Wiley and Sons, 2017. - -.. rubric:: Footnotes - -.. [1] Prior to Cantera 2.6, the sense of the net heat flow was reversed, with positive - :math:`\dot{Q}` representing heat removal from the system. However, the sense of heat - flow through a wall between two reactors was the same, with a positive value - representing heat flow from the left reactor to the right reactor. diff --git a/pages/science/species-thermo.rst b/pages/science/species-thermo.rst deleted file mode 100644 index 646b744a6..000000000 --- a/pages/science/species-thermo.rst +++ /dev/null @@ -1,220 +0,0 @@ -.. slug: species-thermo -.. has_math: true -.. title: Elements and Species - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Elements and Species Thermodynamics</h1> - - .. class:: lead - - All phases in Cantera are made up of one or more species, which in turn - contain one or more elements. - -Elements -======== - -In Cantera, an *element* may refer to a chemical element or an isotope. Note -that definitions of elements are not often needed, since Cantera has definitions -for the standard chemical elements. Explicit element definitions are usually -only needed for isotopes. - -An element can be defined in the YAML format by adding entries to the :ref:`elements -<sec-yaml-elements>` section of the input file. - -Species -======= - -For each species, a species definition is required. - -A species can be defined in the YAML format by adding an entry to the :ref:`species -<sec-yaml-species>` section of the input file. - -Species Name ------------- - -The name of a species may contain letters, numbers, or just about anything else -that is a printable, non-whitespace character. Some example name specifications: - -.. code:: - - CH4 - methane - argon_2+ - CH2(singlet) - -Elemental Composition ---------------------- - -The elemental composition of each species must be specified. -For gaseous species, the elemental composition is well-defined, since the -species represent distinct molecules. For species in solid or liquid solutions, -or on surfaces, there may be several possible ways of defining the species. For -example, an aqueous species might be defined with or without including the water -molecules in the solvation cage surrounding it. - -The special "element" ``E`` is used in representing charged species, where it -specifies the net number of electrons compared to the number needed to form a -neutral species. That is, negatively charged ions will have ``E`` > 0, while -positively charged ions will have ``E`` < 0. - -The number of atoms of an element must be non-negative, with the exception of -electrons. - -For surface species, it is possible to omit the elemental composition, in -which case it is composed of nothing, and represents an empty surface site. This -can also be done to represent vacancies in solids. A charged vacancy can be -defined to be composed solely of electrons. - -Thermodynamic Properties ------------------------- - -The phase models discussed in the `Phases section </science/phase-thermo.html>`__ -implement specific models for the thermodynamic properties appropriate for the -type of phase or interface they represent. Although each one may use different -expressions to compute the properties, they all require thermodynamic property -information for the individual species. For the phase types implemented at -present, the properties needed are: - -1. the molar heat capacity at constant pressure :math:`\hat{c}^\circ_p(T)` for a - range of temperatures and a reference pressure :math:`p^\circ`; -2. the molar enthalpy :math:`\hat{h}(T^\circ, p^\circ)` at :math:`p^\circ` and a reference - temperature :math:`T^\circ`; -3. the absolute molar entropy :math:`\hat{s}(T^\circ, p^\circ)` at :math:`(T^\circ, p^\circ)`. - -The superscript :math:`^\circ` here represents the *reference state*--a specified state -(that is, a set of conditions :math:`T^\circ` and :math:`p^\circ` and fixed chemical -composition) at which thermodynamic properties are known. - -.. _sec-thermo-models: - -Thermodynamic Property Models -============================= - -The models described in this section can be used to provide thermodynamic data -for each species in a phase. Each model implements a different -*parameterization* (functional form) for the heat capacity. Note that there is -no requirement that all species in a phase use the same parameterization; each -species can use the one most appropriate to represent how the heat capacity -depends on temperature. - -Currently, several types are implemented that provide species properties -appropriate for models of ideal gas mixtures, ideal solutions, and pure -compounds. - -The NASA 7-Coefficient Polynomial Parameterization --------------------------------------------------- - -The NASA 7-coefficient polynomial parameterization is used to compute the -species reference-state thermodynamic properties :math:`\hat{c}^\circ_p(T)`, -:math:`\hat{h}^\circ(T)`, and :math:`\hat{s}^\circ(T)`. - -The NASA parameterization represents :math:`\hat{c}^\circ_p(T)` with a fourth-order -polynomial: - -.. math:: - - \frac{\hat{c}_p^\circ(T)}{\overline{R}} = a_0 + a_1 T + a_2 T^2 + a_3 T^3 + a_4 T^4 - - \frac{\hat{h}^\circ (T)}{\overline{R} T} = a_0 + \frac{a_1}{2} T + \frac{a_2}{3} T^2 + - \frac{a_3}{4} T^3 + \frac{a_4}{5} T^4 + \frac{a_5}{T} - - \frac{\hat{s}^\circ(T)}{\overline{R}} = a_0 \ln T + a_1 T + \frac{a_2}{2} T^2 + \frac{a_3}{3} T^3 + - \frac{a_4}{4} T^4 + a_6 - -Note that this is the "old" NASA polynomial form, used in the original NASA -equilibrium program and in Chemkin, which uses 7 coefficients in each of two -temperature regions. It is not compatible with the form used in the most recent -version of the NASA equilibrium program, which uses 9 coefficients for each -temperature region. - -A NASA-7 parameterization can be defined in the YAML format by specifying -:ref:`NASA7 <sec-yaml-nasa7>` as the ``model`` in the species ``thermo`` field. - -.. _sec-thermo-nasa9: - -The NASA 9-Coefficient Polynomial Parameterization --------------------------------------------------- - -The NASA 9-coefficient polynomial parameterization [#McBride2002]_ ("NASA9" for -short) is an extension of the NASA 7-coefficient polynomial parameterization -which includes two additional terms in each temperature region, as well as -supporting an arbitrary number of temperature regions. - -The NASA9 parameterization represents the species thermodynamic properties with -the following equations: - -.. math:: - - \frac{\hat{c}_p^\circ(T)}{\overline{R}} = a_0 T^{-2} + a_1 T^{-1} + a_2 + a_3 T - + a_4 T^2 + a_5 T^3 + a_6 T^4 - - \frac{\hat{h}^\circ(T)}{\overline{R} T} = - a_0 T^{-2} + a_1 \frac{\ln T}{T} + a_2 - + \frac{a_3}{2} T + \frac{a_4}{3} T^2 + \frac{a_5}{4} T^3 + - \frac{a_6}{5} T^4 + \frac{a_7}{T} - - \frac{\hat{s}^\circ(T)}{\overline{R}} = - \frac{a_0}{2} T^{-2} - a_1 T^{-1} + a_2 \ln T - + a_3 T + \frac{a_4}{2} T^2 + \frac{a_5}{3} T^3 + \frac{a_6}{4} T^4 + a_8 - -A common source for species data in the NASA9 format is the -:ref:`NASA ThermoBuild <sec-thermobuild>` tool. - -A NASA-9 parameterization can be defined in the YAML format by specifying -:ref:`NASA9 <sec-yaml-nasa9>` as the ``model`` in the species ``thermo`` field. - -The Shomate Parameterization ----------------------------- - -The Shomate parameterization is: - -.. math:: - - \hat{c}_p^\circ(T) = A + Bt + Ct^2 + Dt^3 + \frac{E}{t^2} - - \hat{h}^\circ(T) = At + \frac{Bt^2}{2} + \frac{Ct^3}{3} + \frac{Dt^4}{4} - - \frac{E}{t} + F - - \hat{s}^\circ(T) = A \ln t + B t + \frac{Ct^2}{2} + \frac{Dt^3}{3} - - \frac{E}{2t^2} + G - -where :math:`t = T / 1000\textrm{ K}`. It requires 7 coefficients :math:`A`, :math:`B`, :math:`C`, :math:`D`, -:math:`E`, :math:`F`, and :math:`G`. This parameterization is used to represent reference-state -properties in the `NIST Chemistry WebBook <http://webbook.nist.gov/chemistry>`__. The values of the -coefficients :math:`A` through :math:`G` should be entered precisely as shown there, with no units -attached. Unit conversions to SI will be handled internally. - -A Shomate parameterization can be defined in the YAML format by specifying -:ref:`Shomate <sec-yaml-shomate>` as the ``model`` in the species -``thermo`` field. - -Constant Heat Capacity ----------------------- - -In some cases, species properties may only be required at a single temperature -or over a narrow temperature range. In such cases, the heat capacity can be -approximated as constant, and simple expressions can be used for the -thermodynamic properties: - -.. math:: - - \hat{c}_p^\circ(T) = \hat{c}_p^\circ(T^\circ) - - \hat{h}^\circ(T) = \hat{h}^\circ\left(T_0\right) + \hat{c}_p^\circ \left(T-T^\circ\right) - - \hat{s}^\circ(T) = \hat{s}^\circ(T_0) + \hat{c}_p^\circ \ln{\left(\frac{T}{T^\circ}\right)} - -The parameterization uses four constants: :math:`T^\circ, \hat{c}_p^\circ(T^\circ), -\hat{h}^\circ(T^\circ)`, and :math:`\hat{s}^\circ(T)`. The default value of :math:`T^\circ` is 298.15 K; the -default value for the other parameters is 0.0. - -A constant heat capacity parameterization can be defined in the YAML format by specifying -:ref:`constant-cp <sec-yaml-constcp>` as the ``model`` in the species ``thermo`` field. - - -.. rubric:: References - -.. [#Mcbride2002] B. J. McBride, M. J. Zehe, S. Gordon. "NASA Glenn Coefficients - for Calculating Thermodynamic Properties of Individual Species," - NASA/TP-2002-211556, Sept. 2002. diff --git a/pages/science/thermodynamics.rst b/pages/science/thermodynamics.rst deleted file mode 100644 index 78a614fa4..000000000 --- a/pages/science/thermodynamics.rst +++ /dev/null @@ -1,111 +0,0 @@ -.. slug: thermodynamics -.. has_math: true -.. title: Calculating phase and species thermodynamics - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Calculating thermodynamic properties in Cantera</h1> - - .. class:: lead - - Here, we describe how Cantera uses species and phase information to calculate - thermodynamic properties. - -Thermodynamic properties typically depend on information at both the species and -phase levels. The user must specify thermodynamic models for both levels, and these -selections must be compatible with one another. For instance: one cannot pair certain -non-ideal species thermodynamic models with an ideal phase model. - -- The user must specify a thermodynamic model for each species and provide inputs - that inform how species properties are calculated. For example, the user specifies - how the reference enthalpy and entropy values for each species are calculated, as a - function of temperature. -- The user also selects a phase model. This model describes how the species interact - with one another to determine phase properties and species specific properties, for - a given thermodynamic state. This includes general - :math:`p`-:math:`\hat{v}`-:math:`T` behavior (for example, calculate the phase - pressure for a given molar volume, temperature, and chemical composition), as well - as how species-specific properties, such as internal energy, entropy, and others - depend on the state variables - -Example: The Ideal Gas Model -============================ - -For a simple example: in the Ideal Gas model, one might use 7-parameter NASA polynomials -to specify the species reference thermodynamic quantities. These would be used to -calculate the reference molar enthalpy :math:`\hat{h}_k^\circ(T)` and entropy -:math:`\hat{s}_k^\circ(T)` for a given species :math:`k` as a function of temperature -:math:`T`. See the `NASA Polynomials Species Thermo entry -</science/species-thermo.html#the-nasa-7-coefficient-polynomial-parameterization>`__ for -more information. - -At the phase level, the Ideal Gas Law provides the :math:`P`-:math:`\hat{v}`-:math:`T` -relationship. The ideal gas law is an example of an equation of state. This is used, for -example, to calculate the pressure as a function of molar volume :math:`\hat{v}`, and -temperature, :math:`T`: - -.. math:: - p = \frac{\overline{R}T}{\hat{v}} - -where :math:`\overline{R}` is the Universal Gas Constant. The `Maxwell relations -<https://en.wikipedia.org/wiki/Maxwell_relations>`__ are used to derive other -thermodynamic properties from the equation of state. With the Ideal Gas phase model, -these reduce to rather simple forms. For example, for a species :math:`k`, the Ideal Gas -molar internal energy :math:`\hat{u}_k` and entropy :math:`\hat{s}_k` are: - -.. math:: - \hat{u}_k = \hat{h}^\circ_k(T) - p\hat{v} - - \hat{s}_k = \hat{s}^\circ_k(T) - \overline{R}\ln\left(\frac{pX_k}{p^\circ}\right) - -where :math:`X_k` is the mole fraction of species :math:`k`, and where :math:`p^\circ` -is the reference pressure at which the properties :math:`\hat{h}_k^\circ(T)` and -:math:`\hat{s}_k^\circ(T)` are known. - -Please click either of the cards below for details on the species and phase models -available in Cantera: - -.. container:: container - :tagname: section - - .. container:: card-deck - - .. container:: card - - .. container:: - :tagname: a - :attributes: href=species-thermo.html - title=Species - - .. container:: card-header section-card - :tagname: div - - Species - - .. container:: card-body - - .. container:: card-text - - The models and equations that Cantera uses to calculate species - thermodynamic properties, such as the NASA 7-parameter polynomial form. - - .. container:: card - - .. container:: - :tagname: a - :attributes: href=phase-thermo.html - title=Phases - - .. container:: card-header section-card - :tagname: div - - Phases - - .. container:: card-body - - .. container:: card-text - - The theory behind some of Cantera's phase models, such as the Ideal Gas Law. - diff --git a/pages/science/transport.rst b/pages/science/transport.rst deleted file mode 100644 index 324ac9af6..000000000 --- a/pages/science/transport.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. slug: transport -.. has_math: true -.. title: Calculating phase and species transport properties and rates - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Calculating transport properties and rates in Cantera</h1> - - .. class:: lead - - Here, we describe how Cantera uses species and phase information to calculate - transport properties and rates. - -Similar to Cantera's approach to `thermodynamic properties -</science/thermodynamics.html>`__, transport property calculations in Cantera depend on -information at both the species and phase levels. The user must specify transport models -for both levels, and these selections must be compatible with one another. - -- The user must specify a transport model for each species and provide inputs that - inform how species properties are calculated. For example, the user provides inputs - that allow Cantera to calculate species collision integrals based on species-specific - Lennard-Jones parameters. -- The user also selects a phase model. This model describes how the species interact - with one another to determine phase-averaged properties (such viscosity or thermal - conductivity) and species specific properties (such as diffusion coefficients), for a - given thermodynamic state. - -Species Transport Coefficients ------------------------------- - -Transport property models in general require coefficients that express the -effect of each species on the transport properties of the phase. Currently, -ideal-gas transport property models are implemented. - -Transport properties can be defined in the YAML format using the -:ref:`transport <sec-yaml-species-transport>` field of a ``species`` entry. - -.. _sec-phase-transport-models: - -Phase Transport Models ----------------------- - -Two transport models are available for use with ideal gas mixtures. The first is a multicomponent -transport model that is based on the model described by Dixon-Lewis [#dl68]_ (see also Kee et al. -[#Kee2017]_). The second is a model that uses the mixture-averaged rule. - - - -.. rubric:: References - -.. [#dl68] G. Dixon-Lewis. Flame structure and flame reaction kinetics, - II: Transport phenomena in multicomponent systems. *Proc. Roy. Soc. A*, - 307:111--135, 1968. - -.. [#Kee2017] R. J. Kee, M. E. Coltrin, P. Glarborg, and H. Zhu. *Chemically Reacting Flow: - Theory and Practice*. 2nd Ed. John Wiley and Sons, 2017. \ No newline at end of file diff --git a/pages/tutorials/MatlabTutorial.rst b/pages/tutorials/MatlabTutorial.rst deleted file mode 100644 index 0328822c6..000000000 --- a/pages/tutorials/MatlabTutorial.rst +++ /dev/null @@ -1,706 +0,0 @@ -.. slug: matlab-tutorial -.. has_math: true -.. title: Matlab Tutorial -.. has_math: true - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Matlab Tutorial</h1> - -Getting Started -=============== - -First, you'll need to install Cantera on your computer. We have instructions for -many platforms in our `Installation section </install/index.html>`__. - -When using Cantera, the first thing you usually need is an object representing -some phase of matter. Here, we'll create a gas mixture. Start MATLAB, and at -the prompt type: - -.. code:: matlabsession - - >> gas1 = GRI30 - -If you have successfully installed the Cantera toolbox, you should see something -like this: - -.. code:: - - gri30: - - temperature 300 K - pressure 101325 Pa - density 0.0818891 kg/m^3 - mean mol. weight 2.01588 amu - - 1 kg 1 kmol - ----------- ------------ - enthalpy 26470.1 5.336e+04 J - internal energy -1.21087e+06 -2.441e+06 J - entropy 64913.9 1.309e+05 J/K - Gibbs function -1.94477e+07 -3.92e+07 J - heat capacity c_p 14311.8 2.885e+04 J/K - heat capacity c_v 10187.3 2.054e+04 J/K - - X Y Chem. Pot. / RT - ------------- ------------ ------------ - H2 1 1 -15.7173 - [ +52 minor] 0 0 - - - -What you have just done is to create an object (``gas1``) that -implements GRI-Mech 3.0, the 53-species, 325-reaction natural gas -combustion mechanism developed by Gregory P. Smith, David M. Golden, -Michael Frenklach, Nigel W. Moriarty, Boris Eiteneer, Mikhail -Goldenberg, C. Thomas Bowman, Ronald K. Hanson, Soonho Song, William -C. Gardiner, Jr., Vitali V. Lissianski, and Zhiwei Qin. (See -http://combustion.berkeley.edu/gri-mech/ for more information about -GRI-Mech 3.0.) - -The ``gas1`` object has properties you would expect for a gas mixture—it has a -temperature, a pressure, species mole and mass fractions, etc. As we'll soon -see, it has many more properties. - -The summary of the state of ``gas1`` printed above shows that new objects -created from the ``gri30.yaml`` input file start out with a temperature of 300 K, -a pressure of 1 atm, and have a composition that consists of only one species, -in this case hydrogen. There is nothing special about H2, it just happens to -be the first species listed in the input file defining GRI-Mech 3.0. In -general, whichever species is listed first will initially have a mole fraction -of 1.0, and all of the others will be zero. - -Setting the State -~~~~~~~~~~~~~~~~~ - -The state of the object can easily be changed. For example: - -.. code:: matlabsession - - >> setTemperature(gas1, 1200); - -sets the temperature to 1200 K (Cantera always uses SI units). After this -statement, calling ``gas1()`` results in: - -.. code:: - - gri30: - - temperature 1200 K - pressure 405300 Pa - density 0.0818891 kg/m^3 - mean mol. weight 2.01588 amu - - 1 kg 1 kmol - ----------- ------------ - enthalpy 1.32956e+07 2.68e+07 J - internal energy 8.34619e+06 1.682e+07 J - entropy 85227.6 1.718e+05 J/K - Gibbs function -8.89775e+07 -1.794e+08 J - heat capacity c_p 15377.9 3.1e+04 J/K - heat capacity c_v 11253.4 2.269e+04 J/K - - X Y Chem. Pot. / RT - ------------- ------------ ------------ - H2 1 1 -17.9775 - [ +52 minor] 0 0 - - -Notice that the temperature has been changed as requested, but the pressure has -changed too. The density and composition have not. - -When setting properties individually, some convention needs to be -adopted to specify which other properties are held constant. This is -because thermodynamics requires that *two* properties (not one) in -addition to composition information be specified to fix the -intensive state of a substance (or mixture). - -Cantera adopts the following convention: only one of the set -(temperature, density, mass fractions) is altered by setting any -single property. In particular: - -- Setting the temperature is done holding density and composition fixed. - (The pressure changes.) -- Setting the pressure is done holding temperature and - composition fixed. (The density changes.) -- Setting the composition is done holding temperature - and density fixed. (The pressure changes). - -If you want to set multiple properties at once, use the :mat:func:`ThermoPhase.set` method. (Note: a -*method* is just the term for a function that acts on an object. In MATLAB, -methods take the object as the first argument.): - -.. code:: matlabsession - - >> set(gas1, 'Temperature', 900.0, 'Pressure', 1.e5); - -This statement sets both temperature and pressure at the same -time. Any number of property/value pairs can be specified in a -call to :mat:func:`ThermoPhase.set`. For example, the following sets the mole fractions -too: - -.. code:: matlabsession - - >> set(gas1, 'Temperature', 900.0, 'Pressure', 1.e5, 'MoleFractions', ... - 'CH4:1,O2:2,N2:7.52'); - -The :mat:func:`ThermoPhase.set` method also accepts abbreviated property names: - -.. code:: matlabsession - - >> set(gas1,'T',900.0,'P',1.e5,'X','CH4:1,O2:2,N2:7.52') - -Either version results in: - -.. code:: - - gri30: - - temperature 900 K - pressure 100000 Pa - density 0.369279 kg/m^3 - mean mol. weight 27.6332 amu - - 1 kg 1 kmol - ----------- ------------ - enthalpy 455660 1.259e+07 J - internal energy 184862 5.108e+06 J - entropy 8529.31 2.357e+05 J/K - Gibbs function -7.22072e+06 -1.995e+08 J - heat capacity c_p 1304.4 3.604e+04 J/K - heat capacity c_v 1003.52 2.773e+04 J/K - - X Y Chem. Pot. / RT - ------------- ------------ ------------ - O2 0.190114 0.220149 -27.9596 - CH4 0.095057 0.0551863 -37.0813 - N2 0.714829 0.724665 -24.935 - [ +50 minor] 0 0 - -Other properties may also be set using :mat:func:`ThermoPhase.set`, including some that -can't be set individually. The following property pairs may be -set: (Enthalpy, Pressure), (IntEnergy, Volume), (Entropy, -Volume), (Entropy, Pressure). In each case, the values of the -extensive properties must be entered *per unit mass*. - -Setting the enthalpy and pressure: - -.. code:: matlabsession - - >> set(gas1, 'Enthalpy', 2*enthalpy_mass(gas1), 'Pressure', 2*oneatm); - -The composition above was specified using a string. The format is a -comma-separated list of <species name>:<relative mole numbers> -pairs. The mole numbers will be normalized to produce the mole -fractions, and therefore they are 'relative' mole numbers. Mass -fractions can be set in this way too by changing ``'X'`` to ``'Y'`` in the -above statement. - -The composition can also be set using an array, which can be -either a column vector or a row vector but must have the same -size as the number of species. For example, to set all 53 mole -fractions to the same value, do this: - -.. code:: matlabsession - - >> x = ones(53,1); % a column vector of 53 ones - >> set(gas1, 'X', x) - -To set the mass fractions to equal values: - -.. code:: matlabsession - - >> set(gas1, 'Y', x) - -Importing multiple phases or interfaces -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A Cantera input file may contain more than one phase specification, -or may contain specifications of interfaces (surfaces). Here we -import definitions of two bulk phases and the interface between them -from file ``diamond.yaml``: - -.. code:: matlabsession - - >> gas2 = Solution('diamond.yaml', 'gas'); % a gas - >> diamond = Solution('diamond.yaml','diamond'); % bulk diamond - >> diamonnd_surf = importInterface('diamond.yaml','diamond_100',... - gas2, diamond); - -Note that the bulk (3D) phases that participate in the surface -reactions must also be passed as arguments to :mat:func:`importInterface`. - -The following command clears all Matlab objects created: - -.. code:: matlabsession - - >> clear all - -and this clears all Cantera objects created: - -.. code:: matlabsession - - >> cleanup - -Working with input files -======================== - -Previously, we used the function :mat:func:`GRI30` to create an object that models an ideal -gas mixture with the species and reactions of GRI-Mech 3.0. Another way to do -this is shown here: - -.. code:: matlabsession - - >> gas1 = Solution('gri30.yaml', 'gri30'); - -Function :mat:func:`Solution` constructs an object representing a phase of -matter by reading in attributes of the phase from a file, which in -this case is ``gri30.yaml``. This file contains several phase -specifications; the one we want here is ``gri30``, which is specified -by the second argument. This file contains a complete specification -of the GRI-Mech 3.0 reaction mechanism, including element data -(name, atomic weight), species data (name, elemental composition, -coefficients to compute thermodynamic and transport properties), and -reaction data (stoichiometry, rate coefficient parameters). - -Input files distributed with Cantera -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Several reaction mechanism files in this format are included in the -Cantera distribution, including ones that model high-temperature -air, a hydrogen/oxygen reaction mechanism, and a few surface -reaction mechanisms. Under Windows, these files may be located in -'``C:\Program Files\Cantera\data``' -depending on how you installed Cantera and the options you -specified. On a Unix/linux/macOS machine, they are usually kept -in the ``data`` subdirectory within the Cantera installation -directory. - -If for some reason Cantera has difficulty finding where these files -are on your system, set the environment variable ``CANTERA_DATA`` to the -directory where they are located. Alternatively, you can call function -:mat:func:`adddir` to add a directory to the Cantera search path: - -.. code:: matlabsession - - >> adddir('/usr/local/cantera/my_data_files'); - -Cantera currently supports input files in the YAML format. Utilities are provided for -converting CTI and XML files (used with older Cantera versions) to YAML. For more info, -see `Converting CTI and XML input files to YAML <legacy2yaml.html>`__. - -To learn more about the input files already available with Cantera and how to -create new input files, see :doc:`Working With Input Files <input-files>`. - -Let's clear out all our Matlab and Cantera objects, before we move on: - -.. code:: matlabsession - - >> clear all - >> cleanup - - -Getting Help -============ - -Suppose you have created a Cantera object and want to know what -methods are available for it, and get help on using the methods. - -.. code:: matlabsession - - >> g = GRI30 - -The first thing you need to know is the MATLAB class object ``g`` -belongs to. Type: - -.. code:: matlabsession - - >> class(g) - -This tells you that ``g`` belongs to a class called ``Solution``. To find -the methods for this class, type - -.. code:: matlabsession - - >> methods Solution - -This command returns only a few method names. These are the ones -directly defined in this class. But ``Solution`` inherits many other -methods from base classes. To see all of its methods, type - -.. code:: matlabsession - - >> methods Solution -full - -Now a long list is printed, along with a specification of the class -the method is inherited from. For example, ``setPressure`` is -inherited from a class ``ThermoPhase``. Don't be concerned at this -point about what these base classes are—we'll come back to them -later. - -Now that you see what methods are available, you can type ``help -<method_name>`` to print help text for any method. For example, - -.. code:: matlabsession - - >> help setTemperature - >> help setMassFractions - >> help rop_net - -For help on how to construct objects of a given class, type ``help -<classname>`` - -.. code:: matlabsession - - >> help Solution - -Now that you know how to get help when you need it, you can -explore using the Cantera Toolbox on your own. But there are a -few more useful things to know, which are described in the next -few sections. - -Chemical Equilibrium -==================== - -To set a gas mixture to a state of chemical equilibrium, use the -:mat:func:`ThermoPhase.equilibrate` method. - -.. code:: matlabsession - - >> set(g,'T',1200.0,'P',oneatm,'X','CH4:0.95,O2:2,N2:7.52') - >> equilibrate(g,'TP') - -The statement above sets the state of object ``g`` to the state of -chemical equilibrium holding temperature and pressure -fixed. Alternatively, the specific enthalpy and pressure can be held -fixed: - -.. code:: matlabsession - - >> disp('fixed H and P:'); - >> set(g,'T',1200.0,'P',oneatm,'X','CH4:0.95,O2:2.0,N2:7.52'); - >> equilibrate(g,'HP') - -Other options are: - -- ``UV`` fixed specific internal energy and specific volume -- ``SV`` fixed specific entropy and specific volume -- ``SP`` fixed specific entropy and pressure - -.. code:: matlabsession - - >> disp('fixed U and V:'); - >> set(g,'T',1200.0,'P',oneatm,'X','CH4:0.95,O2:2,N2:7.52'); - >> equilibrate(g,'UV') - >> disp('fixed S and V:'); - >> set(g,'T',1200.0,'P',oneatm,'X','CH4:0.95,O2:2,N2:7.52'); - >> equilibrate(g,'SV') - >> disp('fixed S and P:'); - >> set(g,'T',1200.0,'P',oneatm,'X','CH4:0.95,O2:2,N2:7.52'); - >> equilibrate(g,'SP') - -How can you tell if :mat:func:`ThermoPhase.equilibrate` has correctly found the -chemical equilibrium state? One way is verify that the net rates of -progress of all reversible reactions are zero. - -Here is the code to do this: - -.. code:: matlabsession - - >> set(g,'T',2000.0,'P',oneatm,'X','CH4:0.95,O2:2,N2:7.52'); - >> equilibrate(g,'TP') - >> rf = rop_f(g); - >> rr = rop_r(g); - >> format short e; - >> for i = 1:nReactions(g) - >> if isReversible(g,i) - >> disp([i, rf(i), rr(i), (rf(i) - rr(i))/rf(i)]); - >> end - >> end - -You might be wondering how :mat:func:`ThermoPhase.equilibrate` works. (Then again, you might not.) -Method :mat:func:`ThermoPhase.equilibrate` invokes Cantera's chemical equilibrium solver, which uses -an element potential method. The element potential method is one of a class of equivalent -'nonstoichiometric' methods that all have the characteristic that the problem reduces to solving a -set of :math:`M` nonlinear algebraic equations, where :math:`M` is the number of elements (not -species). The so-called 'stoichiometric' methods, on the other hand, (including Gibbs minimization), -require solving K nonlinear equations, where :math:`K` is the number of species (usually :math:`K >> -M`). See Smith and Missen, "Chemical Reaction Equilibrium Analysis" for more information on the -various algorithms and their characteristics. - -Cantera uses a damped Newton method to solve these equations, and -does a few other things to generate a good starting guess and to -produce a reasonably robust algorithm. If you want to know more -about the details, look at the -C++ code in `ChemEquil.h <{{% ct_docs doxygen/html/d4/dd4/ChemEquil_8h.html %}}>`__. - -Reaction information and rates -============================== - -Methods are provided that compute many quantities of interest for -kinetics. Some of these are: - -Stoichiometric coefficients -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code:: matlabsession - - >> set(g,'T',1500,'P',oneatm,'X',ones(nSpecies(g),1)); - >> nu_r = stoich_r(g) % reactant stoichiometric coefficient matrix - >> nu_p = stoich_p(g) % product stoichiometric coefficient matrix - >> nu_net = stoich_net(g) % net (product - reactant) stoichiometric coefficient matrix - -For any of these, the ``(k,i)`` matrix element is the stoichiometric -coefficient of species :math:`k` in reaction :math:`i`. Since these coefficient -matrices are very sparse, they are implemented as MATLAB sparse -matrices. - -Reaction rates of progress -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Methods :mat:func:`rop_f`, :mat:func:`rop_r`, and :mat:func:`rop_net` return column vectors -containing the forward, reverse, and net (forward - reverse) rates of progress, respectively, for -all reactions. - -.. code:: matlabsession - - >> qf = rop_f(g); - >> qr = rop_r(g); - >> qn = rop_net(g); - >> rop = [qf, qr, qn] - -This plots the rates of progress - -.. code:: matlabsession - - >> figure(1); - >> bar(rop); - >> legend('forward','reverse','net'); - -Species production rates -~~~~~~~~~~~~~~~~~~~~~~~~ - -Methods :mat:func:`creationRates`, :mat:func:`destructionRates`, and :mat:func:`netProdRates` return -column vectors containing the creation, destruction, and net -production (creation - destruction) rates, respectively, for all species. - -.. code:: matlabsession - - >> cdot = creationRates(g); - >> ddot = destructionRates(g); - >> wdot = netProdRates(g); - >> rates = [cdot, ddot, wdot] - -This plots the production rates: - -.. code:: matlabsession - - >> figure(2); - >> bar(rates); - >> legend('creation','destruction','net'); - -For comparison, the production rates may also be computed -directly from the rates of progress and stoichiometric -coefficients. - -.. code:: matlabsession - - >> cdot2 = nu_p*qf + nu_r*qr; - >> creation = [cdot, cdot2, cdot - cdot2] - >> ddot2 = nu_r*qf + nu_p*qr; - >> destruction = [ddot, ddot2, ddot - ddot2] - >> wdot2 = nu_net * qn; - >> net = [wdot, wdot2, wdot - wdot2] - -Reaction equations -~~~~~~~~~~~~~~~~~~ - -.. code:: matlabsession - - >> e8 = reactionEqn(g,8) % equation for reaction 8 - >> e1_10 = reactionEqn(g,1:10) % equation for rxns 1 - 10 - >> eqs = reactionEqn(g) % all equations - -Equilibrium constants -~~~~~~~~~~~~~~~~~~~~~ - -The equilibrium constants are computed in concentration units, -with concentrations in kmol/m^3. - -.. code:: matlabsession - - >> kc = equil_Kc(g); - >> for i = 1:nReactions(g) - >> disp(sprintf('%50s %13.5g', eqs{i}, kc(i))) - >> end - -Multipliers -~~~~~~~~~~~ - -For each reaction, a multiplier may be specified that is applied -to the forward rate coefficient. By default, the multiplier is -1.0 for all reactions. - -.. code:: matlabsession - - >> for i = 1:nReactions(g) - >> setMultiplier(g, i, 2*i); - >> m = multiplier(g, i); - >> end - -Let's clear out the Matlab and Cantera objects, before moving on: - -.. code:: matlabsession - - >> clear all - >> cleanup - -Transport Properties -==================== - -Methods are provided to compute transport properties. By -default, calculation of transport properties is not enabled. If -transport properties are required, the transport model must be -specified when the gas mixture object is constructed. - -Currently, two models are implemented. Both are based on kinetic -theory expressions, and follow the approach described in Dixon-Lewis -(1968) and Kee, Coltrin, and Glarborg (2003). The first is a full -multicomponent formulation, and the second is a simplification that -uses expressions derived for mixtures with a small number of species -(1 to 3), using approximate mixture rules to average over -composition. - -To use the multicomponent model with GRI-Mech 3.0, call function -GRI30 as follows: - -.. code:: matlabsession - - >> g1 = GRI30('Multi') - -To use the mixture-averaged model: - -.. code:: matlabsession - - >> g2 = GRI30('Mix') - -Both models use a mixture-averaged formulation for the viscosity. - -.. code:: matlabsession - - >> visc = [viscosity(g1), viscosity(g2)] - -The thermal conductivity differs, however. - -.. code:: matlabsession - - >> lambda = [thermalConductivity(g1), thermalConductivity(g2)] - -Binary diffusion coefficients - -.. code:: matlabsession - - >> bdiff1 = binDiffCoeffs(g1) - >> bdiff2 = binDiffCoeffs(g2) - -Mixture-averaged diffusion coefficients. For convenience, the -multicomponent model implements mixture-averaged diffusion -coefficients too. - -.. code:: matlabsession - - >> dmix2 = mixDiffCoeffs(g1) - >> dmix1 = mixDiffCoeffs(g2) - -Multicomponent diffusion coefficients. These are only implemented -if the multicomponent model is used. - -.. code:: matlabsession - - >> dmulti = multiDiffCoeffs(g1) - -Thermal diffusion coefficients. These are only implemented with the -multicomponent model. These will be very close to zero, since -the composition is pure H2. - -.. code:: matlabsession - - >> dt = thermalDiffCoeffs(g1) - -Now change the composition and re-evaluate - -.. code:: matlabsession - - >> set(g1,'X',ones(nSpecies(g1),1)); - >> dt = thermalDiffCoeffs(g1) - -Note that there are no singularities for pure gases. This is -because a very small positive value is added to all mole -fractions for the purpose of computing transport properties. - -Let's clear out the Matlab and Cantera objects, before moving on: - -.. code:: matlabsession - - >> clear all - >> cleanup - -Thermodynamic Properties -======================== - -A variety of thermodynamic property methods are provided. - -.. code:: matlabsession - - >> gas = air - >> set(gas,'T',800,'P',oneatm) - -Temperature, pressure, density: - -.. code:: matlabsession - - >> T = temperature(gas) - >> P = pressure(gas) - >> rho = density(gas) - >> n = molarDensity(gas) - -Species non-dimensional properties: - -.. code:: matlabsession - - >> hrt = enthalpies_RT(gas) % vector of h_k/RT - -Mixture properties per mole: - -.. code:: matlabsession - - >> hmole = enthalpy_mole(gas) - >> umole = intEnergy_mole(gas) - >> smole = entropy_mole(gas) - >> gmole = gibbs_mole(gas) - -Mixture properties per unit mass: - -.. code:: matlabsession - - >> hmass = enthalpy_mass(gas) - >> umass = intEnergy_mass(gas) - >> smass = entropy_mass(gas) - >> gmass = gibbs_mass(gas) - -Let's do one final clearing of the workspace: - -.. code:: matlabsession - - >> clear all - >> cleanup - -Congratulations – Next Steps -============================= - -Congratulations—you have finished the Cantera Matlab tutorial! You should now -be ready to begin using Cantera on your own. Please see the Next Steps -section on the `Getting Started <index.html#cantera-next-steps>`__ page, for assistance with -intermediate and advanced Cantera functionality. Good luck! diff --git a/pages/tutorials/PythonTutorial.rst b/pages/tutorials/PythonTutorial.rst deleted file mode 100644 index 1686d41dc..000000000 --- a/pages/tutorials/PythonTutorial.rst +++ /dev/null @@ -1,549 +0,0 @@ -.. slug: python-tutorial -.. has_math: true -.. title: Python Tutorial - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Python Tutorial</h1> - -Getting Started -=============== - -First, you'll need to install Cantera on your computer. We have instructions for -many platforms in our `Installation section </install/index.html>`__. - -Start by opening an interactive Python session, for example by running `IPython -<http://ipython.org/>`__. Import the Cantera Python module and NumPy by running: - -.. code:: pycon - - >>> import cantera as ct - >>> import numpy as np - -When using Cantera, the first thing you usually need is an object representing: -some phase of matter. Here, we'll create a gas mixture - -.. code:: pycon - - >>> gas1 = ct.Solution('gri30.yaml') - -To view the state of the mixture, *call* the ``gas1`` object as if it were a -function: - -.. code:: pycon - - >>> gas1() - -You should see something like this: - -.. code:: - - gri30: - - temperature 300 K - pressure 1.0133e+05 Pa - density 0.081894 kg/m^3 - mean mol. weight 2.016 kg/kmol - phase of matter gas - - 1 kg 1 kmol - --------------- --------------- - enthalpy 26469 53361 J - internal energy -1.2108e+06 -2.441e+06 J - entropy 64910 1.3086e+05 J/K - Gibbs function -1.9447e+07 -3.9204e+07 J - heat capacity c_p 14311 28851 J/K - heat capacity c_v 10187 20536 J/K - - mass frac. Y mole frac. X chem. pot. / RT - --------------- --------------- --------------- - H2 1 1 -15.717 - [ +52 minor] 0 0 - -What you have just done is to create an object, ``gas1`` that implements GRI- -Mech 3.0, the 53-species, 325-reaction natural gas combustion mechanism -developed by Gregory P. Smith, David M. Golden, Michael Frenklach, Nigel W. -Moriarty, Boris Eiteneer, Mikhail Goldenberg, C. Thomas Bowman, Ronald K. -Hanson, Soonho Song, William C. Gardiner, Jr., Vitali V. Lissianski, and -Zhiwei Qin. See http://combustion.berkeley.edu/gri-mech/ for more information. - -The ``gas1`` object has properties you would expect for a gas mixture - it has a -temperature, a pressure, species mole and mass fractions, etc. As we'll soon -see, it has many more properties. - -The summary of the state of ``gas1`` printed above shows that new objects -created from the ``gri30.yaml`` input file start out with a temperature of 300 K, -a pressure of 1 atm, and have a composition that consists of only one species, -in this case hydrogen. There is nothing special about H2 - it just happens to -be the first species listed in the input file defining GRI-Mech 3.0. In -general, whichever species is listed first will initially have a mole fraction -of 1.0, and all of the others will be zero. - -Setting the State -~~~~~~~~~~~~~~~~~ - -The state of the object can easily be changed. For example: - -.. code:: pycon - - >>> gas1.TP = 1200, 101325 - -sets the temperature to 1200 K and the pressure to 101325 Pa (Cantera always -uses SI units). After this statement, calling ``gas1()`` results in: - -.. code:: - - gri30: - - temperature 1200 K - pressure 1.0133e+05 Pa - density 0.020473 kg/m^3 - mean mol. weight 2.016 kg/kmol - phase of matter gas - - 1 kg 1 kmol - --------------- --------------- - enthalpy 1.3295e+07 2.6802e+07 J - internal energy 8.3457e+06 1.6825e+07 J - entropy 85222 1.7181e+05 J/K - Gibbs function -8.8972e+07 -1.7937e+08 J - heat capacity c_p 15377 31000 J/K - heat capacity c_v 11253 22686 J/K - - mass frac. Y mole frac. X chem. pot. / RT - --------------- --------------- --------------- - H2 1 1 -17.978 - [ +52 minor] 0 0 - -Thermodynamics generally requires that *two* properties in addition to -composition information be specified to fix the intensive state of a substance -(or mixture). The state of the mixture can be set using several combinations -of two properties. The following are all equivalent: - -.. code:: pycon - - >>> gas1.TP = 1200, 101325 # temperature, pressure - >>> gas1.TD = 1200, 0.0204723 # temperature, density - >>> gas1.HP = 1.32956e7, 101325 # specific enthalpy, pressure - >>> gas1.UV = 8.34619e6, 1/0.0204723 # specific internal energy, specific volume - >>> gas1.SP = 85227.6, 101325 # specific entropy, pressure - >>> gas1.SV = 85227.6, 1/0.0204723 # specific entropy, specific volume - -In each case, the values of the extensive properties must be entered *per unit -mass*. - -Properties may be read independently or together: - -.. code:: pycon - - >>> gas1.T - 1200.0 - >>> gas1.h - 13295567.68 - >>> gas1.UV - (8346188.494954427, 48.8465747765848) - -The composition can be set in terms of either mole fractions (``X``) or mass -fractions (``Y``): - -.. code:: pycon - - >>> gas1.X = 'CH4:1, O2:2, N2:7.52' - -Mass and mole fractions can also be set using ``dict`` objects, which is convenient in cases where -the composition is stored in a variable or being computed: - -.. code:: pycon - - >>> phi = 0.8 - >>> gas1.X = {'CH4':1, 'O2':2/phi, 'N2':2*3.76/phi} - -When the composition alone is changed, the temperature and density are held -constant. This means that the pressure and other intensive properties will -change. The composition can also be set in conjunction with the intensive -properties of the mixture: - -.. code:: pycon - - >>> gas1.TPX = 1200, 101325, 'CH4:1, O2:2, N2:7.52' - >>> gas1() - -results in: - -.. code:: - - gri30: - - temperature 1200 K - pressure 1.0133e+05 Pa - density 0.28063 kg/m^3 - mean mol. weight 27.633 kg/kmol - phase of matter gas - - 1 kg 1 kmol - --------------- --------------- - enthalpy 8.6193e+05 2.3818e+07 J - internal energy 5.0087e+05 1.3841e+07 J - entropy 8914.2 2.4633e+05 J/K - Gibbs function -9.8351e+06 -2.7178e+08 J - heat capacity c_p 1397.3 38611 J/K - heat capacity c_v 1096.4 30296 J/K - - mass frac. Y mole frac. X chem. pot. / RT - --------------- --------------- --------------- - O2 0.22014 0.19011 -28.747 - CH4 0.055187 0.095057 -35.961 - N2 0.72467 0.71483 -25.679 - [ +50 minor] 0 0 - - -The composition above was specified using a string. The format is a comma- -separated list of ``<species name>:<relative mole numbers>`` pairs. The mole -numbers will be normalized to produce the mole fractions, and therefore they -are "relative" mole numbers. Mass fractions can be set in this way too by -changing ``X`` to ``Y`` in the above statements. - -The composition can also be set using an array, which must have the same size -as the number of species. For example, to set all 53 mole fractions to the -same value, do this: - -.. code:: pycon - - >>> gas1.X = np.ones(53) # NumPy array of 53 ones - -Or, to set all the mass fractions to equal values: - -.. code:: pycon - - >>> gas1.Y = np.ones(53) - -When setting the state, you can control what properties are held constant by -passing the special value ``None`` to the property setter. For example, to -change the specific volume to 2.1 m\ :sup:`3`\ /kg while holding entropy constant: - -.. code:: pycon - - >>> gas1.SV = None, 2.1 - -Or to set the mass fractions while holding temperature and pressure constant: - -.. code:: pycon - - >>> gas1.TPX = None, None, 'CH4:1.0, O2:0.5' - -Working with a Subset of Species -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Many properties of a :py:class:`cantera.Solution` provide values for each species present in the -phase. If you want to get values only for a subset of these species, you can use -Python's "slicing" syntax to select data for just the species of interest. To -get the mole fractions of just the major species in ``gas1``, in the order -specified, you can write: - -.. code:: pycon - - >>> Xmajor = gas1['CH4','O2','CO2','H2O','N2'].X - -If you want to use the same set of species repeatedly, you can keep a reference -to the sliced phase object: - -.. code:: pycon - - >>> major = gas1['CH4','O2','CO2','H2O','N2'] - >>> cp_major = major.partial_molar_cp - >>> wdot_major = major.net_production_rates - -The slice object and the original object share the same internal state, so -modifications to one will affect the other. - -Working With Mechanism Files -============================ - -In previous example, we created an object that models an ideal gas mixture -with the species and reactions of GRI-Mech 3.0, using the ``gri30.yaml`` input -file included with Cantera. Several other reaction mechanism files are -included with Cantera, including ones that model high- temperature air, -a hydrogen/oxygen reaction mechanism, and a few surface -reaction mechanisms. These files are usually located in the ``data`` -subdirectory of the Cantera installation directory, for example ``C:\Program Files\Cantera\data`` -on Windows or ``/usr/local/cantera/data/`` on -Unix/Linux/Mac OS X machines, depending on how you installed Cantera and the -options you specified. - -If for some reason Cantera has difficulty finding where these files are on your -system, set environment variable ``CANTERA_DATA`` to the directory or -directories (separated using ``;`` on Windows or ``:`` on other operating -systems) where they are located. Alternatively, you can call function -:py:func:`add_directory` to add a directory to the Cantera search path: - -.. code:: pycon - - >>> ct.add_directory('~/cantera/my_data_files') - -Cantera input files are plain text files, and can be created with any text -editor. See the document :doc:`Working With Input Files <input-files>` for more -information. - -A Cantera input file may contain more than one phase specification, or may -contain specifications of interfaces (surfaces). Here we import definitions of -two bulk phases and the interface between them from file ``diamond.yaml``: - -.. code:: pycon - - >>> gas2 = ct.Solution('diamond.yaml', 'gas') - >>> diamond = ct.Solution('diamond.yaml', 'diamond') - >>> diamond_surf = ct.Interface('diamond.yaml' , 'diamond_100', - ... [gas2, diamond]) - -Note that the bulk (3D) phases that participate in the surface reactions must -also be passed as arguments to :py:class:`Interface`. - -Converting CK-format files -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -See the :doc:`Converting CK-format Files <ck2yaml-tutorial>` documentation for -information on how to convert from CK-format to Cantera's YAML format. - -Getting Help -============ - -In addition to the Sphinx-generated `Python documentation </documentation/index.html#Python>`__, -documentation of the Python classes and their methods can be accessed from -within the Python interpreter as well. - -Suppose you have created a Cantera object and want to know what methods are -available for it, and get help on using the methods: - -.. code:: pycon - - >>> g = ct.Solution('gri30.yaml') - -To get help on the Python class that this object is an instance of: - -.. code:: pycon - - >>> help(g) - -For a simple list of the properties and methods of this object: - -.. code:: pycon - - >>> dir(g) - -To get help on a specific method, such as the ``species_index`` method: - -.. code:: pycon - - >>> help(g.species_index) - -For properties, getting the documentation is slightly trickier, as the usual -method will give you the help for the *result*. For example: - -.. code:: pycon - - >>> help(g.T) - -will provide help on Python's ``float`` class. To get the help for the -temperature property, ask for the attribute of the class object itself: - -.. code:: pycon - - >>> help(g.__class__.T) - -If you are using the IPython shell, help can also be obtained using the `?` -syntax: - -.. code:: python - - In[1]: g.species_index? - -Chemical Equilibrium -==================== - -To set a gas mixture to a state of chemical equilibrium, use the equilibrate -method: - -.. code:: pycon - - >>> import cantera as ct - >>> g = ct.Solution('gri30.yaml') - >>> g.TPX = 300.0, ct.one_atm, 'CH4:0.95,O2:2,N2:7.52' - >>> g.equilibrate('TP') - -The above statement sets the state of object ``g`` to the state of chemical -equilibrium holding temperature and pressure fixed. Alternatively, the -specific enthalpy and pressure can be held fixed: - -.. code:: pycon - - >>> g.TPX = 300.0, ct.one_atm, 'CH4:0.95,O2:2,N2:7.52' - >>> g.equilibrate('HP') - -Other options are: - -- ``UV``: fixed specific internal energy and specific volume -- ``SV``: fixed specific entropy and specific volume -- ``SP``: fixed specific entropy and pressure - -How can you tell if ``equilibrate`` has correctly found the chemical equilibrium -state? One way is verify that the net rates of progress of all reversible -reactions are zero. Here is the code to do this: - -.. code:: pycon - - >>> g.TPX = 300.0, ct.one_atm, 'CH4:0.95,O2:2,N2:7.52' - >>> g.equilibrate('HP') - - >>> rf = g.forward_rates_of_progress - >>> rr = g.reverse_rates_of_progress - >>> for i in range(g.n_reactions): - ... if g.reaction(i).reversible and rf[i] != 0.0: - ... print(' %4i %10.4g ' % (i, (rf[i] - rr[i])/rf[i])) - -If the magnitudes of the numbers in this list are all very small, then each -reversible reaction is very nearly equilibrated, which only occurs if the gas -is in chemical equilibrium. - -You might be wondering how ``equilibrate`` works. (Then again, you might not). -Method ``equilibrate`` invokes Cantera's chemical equilibrium solver, which uses -an element potential method. The element potential method is one of a class of -equivalent *nonstoichiometric* methods that all have the characteristic that -the problem reduces to solving a set of :math:`M` nonlinear algebraic equations, where -:math:`M` is the number of elements (not species). The so-called *stoichiometric* -methods, on the other hand, (including Gibbs minimization), require solving :math:`K` -nonlinear equations, where :math:`K` is the number of species (usually :math:`K >> M`). See -Smith and Missen, "Chemical Reaction Equilibrium Analysis" for more -information on the various algorithms and their characteristics. - -Cantera uses a damped Newton method to solve these equations, and does a few -other things to generate a good starting guess and to produce a reasonably -robust algorithm. If you want to know more about the details, look at the -C++ code in `ChemEquil.h <{{% ct_docs doxygen/html/d4/dd4/ChemEquil_8h.html %}}>`__. - -Chemical Kinetics -================= - -:py:class:`cantera.Solution` objects are also :py:class:`Kinetics` objects, and provide all of the methods -necessary to compute the thermodynamic quantities associated with each reaction, -reaction rates, and species creation and destruction rates. They also provide -methods to inspect the quantities that define each reaction such as the rate -constants and the stoichiometric coefficients. The rate calculation functions -are used extensively within Cantera's -`reactor network model <{{% ct_docs sphinx/html/cython/zerodim.html#sec-cython-zerodim %}}>`__ -and `1D flame model <{{% ct_docs sphinx/html/cython/onedim.html#sec-cython-onedim %}}>`__. - -Information about individual reactions that is independent of the thermodynamic -state can be obtained by accessing :py:class:`cantera.Reaction` objects with the -:py:func:`Kinetics.reaction` method: - -.. code:: pycon - - >>> g = ct.Solution('gri30.yaml') - >>> r = g.reaction(2) # get a Reaction object - >>> r - H2 + O <=> H + OH <Reaction(Arrhenius)> - - >>> r.reactants - {'H2': 1.0, 'O': 1.0} - >>> r.products - {'H': 1.0, 'OH': 1.0} - -.. - @todo: fix :py:attr:`ReactionRate.input_data` below (does not work in Nikola/Sphinx) - -Information about specific reaction rate parameterizations should be queried using the -``input_data`` property, which returns a YAML-compatible dictionary that represents -input data needed to create the corresponding rate object: - -.. code:: pycon - - >>> r.rate - <ArrheniusRate at 1c0a71f02b0> - >>> r.rate.input_data - {'rate-constant': {'A': 38.7, 'b': 2.7, 'Ea': 26191840.0}} - -If we are interested in only certain types of reactions, we can use this -information to filter the full list of reactions to find the just the ones of -interest. For example, here we find the indices of just those reactions which -convert ``CO`` into ``CO2``: - -.. code:: pycon - - >>> II = [i for i,r in enumerate(g.reactions()) - ... if 'CO' in r.reactants and 'CO2' in r.products] - >>> for i in II: - ... print(g.reaction(i).equation) - CO + O (+M) <=> CO2 (+M) - CO + O2 <=> CO2 + O - CO + OH <=> CO2 + H - CO + HO2 <=> CO2 + OH - -(Actually, we should also include reactions where the reaction is written such -that ``CO2`` is a reactant and ``CO`` is a product, but for this example, we'll -just stick to this smaller set of reactions.) Now, let's set the composition to -an interesting equilibrium state: - -.. code:: pycon - - >>> g.TPX = 300, 101325, {'CH4':0.6, 'O2':1.0, 'N2':3.76} - >>> g.equilibrate('HP') - -We can verify that this is an equilibrium state by seeing that the net reaction -rates are essentially zero: - -.. code:: pycon - - >>> g.net_rates_of_progress[II] - array([ 4.06576e-20, -5.50571e-21, 0.00000e+00, -4.91279e-20]) - -Now, let's see what happens if we decrease the temperature of the mixture: - -.. code:: pycon - - >>> g.TP = g.T-100, None - >>> g.net_rates_of_progress[II] - array([ 3.18645e-05, 5.00490e-08, 1.05965e-01, 2.89503e-06]) - -All of the reaction rates are positive, favoring the formation of ``CO2`` from -``CO``, with the third reaction, ``CO + OH <=> CO2 + H`` proceeding the fastest. -If we look at the enthalpy change associated with each of these reactions: - -.. code:: pycon - - >>> g.delta_enthalpy[II] - array([ -5.33035e+08, -2.23249e+07, -8.76650e+07, -2.49170e+08]) - -we see that the change is negative in each case, indicating a net release of -thermal energy. The total heat release rate can be computed either from the -reaction rates: - -.. code:: pycon - - >>> np.dot(g.net_rates_of_progress, g.delta_enthalpy) - -58013370.720881931 - -or from the species production rates: - -.. code:: pycon - - >>> np.dot(g.net_production_rates, g.partial_molar_enthalpies) - -58013370.720881805 - -The contribution from just the selected reactions is: - -.. code:: pycon - - >>> np.dot(g.net_rates_of_progress[II], g.delta_enthalpy[II]) - -9307123.2625651453 - -Or about 16% of the total heat release rate. - -Next Steps -========== - -Congratulations! You have finished the Cantera Python tutorial. You should now -be ready to begin using Cantera on your own. Please see the Next Steps -section on the `Getting Started <index.html#cantera-next-steps>`__ page, for assistance with -intermediate and advanced Cantera functionality. Good luck! diff --git a/pages/tutorials/ck2yaml-tutorial.rst b/pages/tutorials/ck2yaml-tutorial.rst deleted file mode 100644 index 78bba3478..000000000 --- a/pages/tutorials/ck2yaml-tutorial.rst +++ /dev/null @@ -1,304 +0,0 @@ -.. title: Converting Chemkin Format Files -.. slug: ck2yaml-tutorial -.. has_math: true - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Converting Chemkin-format files</h1> - - .. class:: lead - - If you want to convert a Chemkin-format file to YAML format, or you're - having errors when you try to do so, this section will help. - -ck2yaml -------- - -Many existing reaction mechanism files are in **CK format**, by which we mean -the input file format developed for use with the Chemkin-II software package -(and subsequent releases) as specified in the report describing the Chemkin -software [SAND89]_. - -Cantera comes with a converter utility program ``ck2yaml`` (or ``ck2yaml.py``) -that converts CK format into Cantera format. This program should be run from -the command line first to convert any CK files you plan to use into Cantera -format (YAML format). *(New in Cantera 2.5)* - -Usage: - -.. code:: bash - - ck2yaml [--input=<filename>] - [--thermo=<filename>] - [--transport=<filename>] - [--surface=<filename>] - [--name=<name>] - [--extra=<filename>] - [--output=<filename>] - [--single-intermediate-temperature] - [--permissive] - [--quiet] - [--no-validate] - [-d | --debug] - -Each of the terms in square brackets is an option that can be passed on the -command line to ``ck2yaml``. - -- ``--input``: This is the chemistry input file, containing a list of all the - element names that are used, a list of all the species names, and a list of - all the reactions to be considered between the species. This file can also - optionally contain thermodynamic information for the species. - -- ``--thermo``: If the ``--input`` file does not contain the thermodynamic data, - a separate file containing this information must be specified to the - ``--thermo`` option. - -- ``--transport``: The ``--input`` file can also optionally contain transport - information for the species. If it does not, and the user wishes to use a part - of Cantera that relies on some transport properties, the ``--transport`` - option must be used to specify the file containing all the transport data for - the species. - -- ``--surface``: For surface mechanisms, this file defines the surface species - and reactions occurring on the surface. Gas phase species and reactions are - defined in the file specified by the ``--input`` option. - -- ``--name``: This specifies the name of the phase in the resulting YAML file. - The default is ``gas``. - -- ``--extra``: This option specifies a YAML file which can be used to add to the - ``description`` field or to define custom fields that are included in the YAML - output. - -- ``--output``: Specifies the output file name. By default, the output file name - is the input file name with the extension changed to ``.yaml``. - -- ``--single-intermediate-temperature``: This option should be used with thermo data - where only a single break temperature is used and the last value in the first line of - each species thermo entry is the molecular weight instead. - -- ``--permissive``: This option allows certain recoverable parsing errors (for - example, duplicate thermo data) to be ignored. - -- ``--quiet``: Suppresses warning messages, such those about duplicate thermo - data. - -- ``--no-validate``: Disables the validation step, where the YAML mechanism is imported - in Cantera to check for errors such as unlabeled duplicate reactions and discontinuous - thermodynamic data. - -- ``--debug``: Enables additional debugging output that may be helpful in identifying - problems in the input files or ``ck2yaml`` itself. - -Example: - -.. code:: bash - - ck2yaml --input=chem.inp --thermo=therm.dat --transport=tran.dat - -If the ``ck2yaml`` script is not on your path but the Cantera Python module is, -``ck2yaml`` can also be used by running: - -.. code:: bash - - python -m cantera.ck2yaml --input=chem.inp --thermo=therm.dat --transport=tran.dat - -An input file containing only species definitions (which can be referenced from -phase definitions in other input files) can be created by specifying only a -thermo file. - -Debugging common errors in CK files ------------------------------------ - -.. note:: - - Many existing CK format files cause errors in ``ck2yaml`` when they are - processed. Some of these errors may be avoided by specifying the - ``--permissive`` option. This option allows certain recoverable parsing errors - (for example, duplicate transport or thermodynamic data) to be ignored. Other - errors may be caused by incorrect formatting of lines in one or more of the - input files. - -When ``ck2yaml`` encounters an error, it attempts to print the surrounding -information to help you to locate the error. Many of the most common errors -are due to an inconsistency of the input files from their standard, as defined -in the report for Chemkin referenced above. These errors include: - -* Each section of the input files must start with a keyword representing that - section and end with the keyword ``END``. Keywords that may begin a section - include: - - - ``ELEMENTS`` or ``ELEM`` - - ``SPECIES`` or ``SPEC`` - - ``THERMO`` or ``THERMO ALL`` - - ``REACTIONS`` or ``REAC`` - - ``TRANSPORT`` - -* The thermodynamic data is read in a fixed format. This means that each - column of the input has a particular meaning. *Many common errors are - generated because information is missing or in the wrong column. Check - thoroughly for extraneous or missing spaces.* The format for each - thermodynamic entry should be as follows:: - - N2 N 2 G200.000 6000.000 1000.00 1 - 2.95258000E+00 1.39690000E-03-4.92632000E-07 7.86010000E-11-4.60755000E-15 2 - -9.23949000E+02 5.87189000E+00 3.53101000E+00-1.23661000E-04-5.02999000E-07 3 - 2.43531000E-09-1.40881000E-12-1.04698000E+03 2.96747000E+00 4 - - The following table is adapted from the Chemkin manual [SAND89]_ to describe the - column positioning of each required part of the entry. Empty columns should be - filled with spaces. - - +---------+-------------------------------------+--------+ - |Line No. | Contents | Column | - +=========+=====================================+========+ - | 1 | Species Name | 1–18 | - +---------+-------------------------------------+--------+ - | 1 | Date (Optional) | 19–24 | - +---------+-------------------------------------+--------+ - | 1 | Atomic Symbols and formula | 25–44 | - +---------+-------------------------------------+--------+ - | 1 | Phase of species (S, L, G) | 45 | - +---------+-------------------------------------+--------+ - | 1 | Low temperature | 46–55 | - +---------+-------------------------------------+--------+ - | 1 | High temperature | 56–65 | - +---------+-------------------------------------+--------+ - | 1 | Common temperature | 66–73 | - +---------+-------------------------------------+--------+ - | 1 | Additional Atomic Symbols | 74–78 | - +---------+-------------------------------------+--------+ - | 1 | The integer ``1`` | 80 | - +---------+-------------------------------------+--------+ - | 2 | Coefficients :math:`a_1` | 1–75 | - | | to :math:`a_5` for the upper | | - | | temperature interval | | - +---------+-------------------------------------+--------+ - | 2 | The integer ``2`` | 80 | - +---------+-------------------------------------+--------+ - | 3 | Coefficients :math:`a_6,\ a_7` | 1–75 | - | | for the upper temperature interval, | | - | | and :math:`a_1,\ a_2,\ a_3` for | | - | | the lower temperature interval | | - +---------+-------------------------------------+--------+ - | 3 | The integer ``3`` | 80 | - +---------+-------------------------------------+--------+ - | 4 | Coefficients :math:`a_4` through | 1–60 | - | | :math:`a_7` for the lower | | - | | temperature interval | | - +---------+-------------------------------------+--------+ - | 4 | The integer ``4`` | 80 | - +---------+-------------------------------------+--------+ - - The first 18 columns are reserved for the species name. The name assigned - to the species in the thermodynamic data must be the same as the species - name defined in the ``SPECIES`` section. If the species name is shorter - than 18 characters, the rest of the characters should be filled by spaces. - The next six columns (columns 19–24) are typically used to write a date; - they are not used further. The next 20 columns (25–44) are used to - specify the elemental composition of the species. In column 45, the phase - of the species (``S``, ``L``, or ``G`` for solid, liquid, or gas - respectively) should be specified. The next 28 columns are reserved for - the temperatures that delimit the ranges of the polynomials specified on - the next several lines. The first two temperatures have a width of 10 - columns each (46–55 and 56–65), and represent the lowest temperature and - highest temperature for which the polynomials are valid. The last - temperature has a width of 8 columns (66–73) and is the **common** - temperature, where the switch from low to high occurs. The next 5 columns - (74–78) are reserved for atomic symbols and are usually left blank for - the default behavior. Column 79 is blank and finally, the row is ended in - column 80 with the integer ``1``. - - The next three lines of the thermodynamic entry have a similar format. - They contain the coefficients of the polynomial described in - :ref:`Thermodynamic Property Models <sec-thermo-models>` for the NASA - 7-coefficient polynomial formulation. - The second row of the thermo entry (the first after the information row) - contains the first five coefficients that apply to the temperature range - between the midpoint and the upper limit. 15 columns are alloted for each - coefficient (for a total of 75 columns), with no spaces between them. - Although the entry above shows spaces between positive coefficients, it is - to be noted that this is done only for formatting consistency with other - lines that contain negative numbers. After the coefficients, four spaces - in columns 76–79 are followed by the integer ``2`` in column 80. On the - next line, the last two coefficients for the upper temperature range and - the first three coefficients for the lower temperature range are - specified. Once again, this takes up the first 75 columns, columns 76–79 - are blank, and the integer ``3`` is in column 80. Finally, on the last - line of a particular entry, the last four coefficients of the lower - temperature range are specified in columns 1–60, 19 blank spaces are - present, and the integer ``4`` is in column 80. The 19 blank spaces in the - last line are part of the standard. However, since the original Chemkin - interpreter ignored those spaces, researchers began using that space to - store additional information that was not necessary for the input file. - Although these numbers create an error in ``ck2yaml`` if present, they are - harmless and can be ignored by using the ``--permissive`` option. - - If the number of atoms of an element in a thermodynamic entry has more than 3 - digits, it will cause a conversion error. To avoid the error, the element - symbol should have a ``0`` in the first line of the entry. An ampersand - (``&``) is added after the index of the first line, and the element symbols - and their amounts should be written on the next line as follows:: - - BIN6J PYRENEJ1 C 0H 0 0 0G 300.000 5000.000 1401.000 1& - C 778 H 263 - 3.63345177E+01 3.13968020E-02-1.09044660E-05 1.71125597E-09-1.00056355E-13 2 - 4.05143093E+04-1.77494305E+02-1.20603441E+01 1.59247554E-01-1.41562602E-04 3 - 6.26071650E-08-1.09305161E-11 5.56473533E+04 7.68451211E+01 4 - - or on separate lines with ampersand (``&``) as the last character on the line:: - - BIN6 PYRENE C 0H 0 0 0G 300.000 5000.000 1401.000 1& - C 778& - H 264 - 3.65839677E+01 3.36764102E-02-1.16783938E-05 1.83077466E-09-1.06963777E-13 2 - 9.29809483E+03-1.81272070E+02-1.29758980E+01 1.63790064E-01-1.43851166E-04 3 - 6.31057915E-08-1.09568047E-11 2.48866399E+04 7.94950474E+01 4 - -* It may be the case that scientific formatted numbers are missing the ``E``. - In this case, numbers often show up as ``1.1+01``, when they should be - ``1.1E+01``. You can fix this with a Regular Expression "find and replace":: - - Find: (\d+\.\d+)([+-]\d+) - Replace: \1E\2 - -* The transport data file also has a specified format, as described in - [SAND98]_, although the format is not as strict as for the thermodynamic - entries. In particular, the first 15 columns of a line are reserved for - the species name. *One common source of errors is a species that is present - in the transport data file, but not in the thermodynamic data or in - the species list; or a species that is present in the species list but - not the transport data file.* The rest of the columns on a given line have - no particular format, but must be present in the following order: - - +------------------+------------------------------------------------------------+ - | Parameter Number | Parameter Name | - +==================+============================================================+ - | 1 | An integer with value 0, 1, or 2 indicating | - | | monatomic, linear, or non-linear molecular geometry. | - +------------------+------------------------------------------------------------+ - | 2 | The Lennard-Jones potential well depth | - | | :math:`\varepsilon/k_B` in Kelvin | - +------------------+------------------------------------------------------------+ - | 3 | The Lennard-Jones collision diameter :math:`\sigma` | - | | in Angstrom | - +------------------+------------------------------------------------------------+ - | 4 | The dipole moment :math:`\mu` in Debye | - +------------------+------------------------------------------------------------+ - | 5 | The polarizability :math:`\alpha` in Angstroms cubed | - +------------------+------------------------------------------------------------+ - | 6 | The rotational relaxation collision number | - | | :math:`Z_{rot}` at 298 K | - +------------------+------------------------------------------------------------+ - - Another common error is if all 6 of these numbers are not present for every - species. - -.. [SAND89] See R. J. Kee, F. M. Rupley, and J. A. Miller, Sandia National - Laboratories Report SAND89-8009 (1989). - http://www.osti.gov/scitech/biblio/5681118 - -.. [SAND98] See R. J. Kee, G. Dixon-Lewis, J. Warnatz, M. E. Coltrin, J. A. Miller, - H. K. Moffat, Sandia National Laboratories Report SAND86-8246B (1998). diff --git a/pages/tutorials/cxx-guide/compiling.rst b/pages/tutorials/cxx-guide/compiling.rst deleted file mode 100644 index a17c9eb8f..000000000 --- a/pages/tutorials/cxx-guide/compiling.rst +++ /dev/null @@ -1,279 +0,0 @@ -.. title: Compiling Cantera C++ Programs -.. _sec-compiling-cplusplus: - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Compiling Cantera C++ Programs</h1> - - .. class:: lead - - This guide shows you how to build C++ programs that use Cantera's features. Note: - This section is about compiling applications that use the Cantera library; - instructions to compile the Cantera library are over :doc:`over here - <compiling-install>`. - -Build Systems -************* - -In general, it should be possible to use Cantera with any build system by -specifying the necessary header and library paths, as well as the appropriate compiler -and linker options. The correct options and paths depend on your system configuration -and the options that were used to compile Cantera. Cantera is installed with examples -and configuration data that will help with determining the correct options for some -common build systems. - -pkg-config -========== - -On systems where the ``pkg-config`` program is installed, it can be used to -determine the correct compiler and linker flags for use with Cantera. For -example: - -.. code:: bash - - g++ myProgram.cpp -o myProgram $(pkg-config --cflags --libs cantera) - -It can also be used to populate variables in a Makefile: - -.. code:: make - - CFLAGS += $(shell pkg-config --cflags cantera) - LIBS += $(shell pkg-config --libs cantera) - -Or in an SConstruct file: - -.. code:: python - - env.ParseConfig("pkg-config --cflags --libs cantera") - -Note that ``pkg-config`` will work only if it can find the ``cantera.pc`` -file. If Cantera's libraries are not installed in a standard location such as -``/usr/lib`` or ``/usr/local/lib``, you may need to set the ``PKG_CONFIG_PATH`` -environment variable appropriately before using ``pkg-config``, for example by running: - -.. code:: bash - - export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/path/to/lib/pkgconfig - -where ``/path/to/lib`` should be replaced by Cantera's library installation path. - -``pkg-config`` is available through system package managers for most Linux -distributions, and can be installed using Conda or Homebrew on macOS. - -SCons -===== - -SCons is a multi-platform, Python-based build system. It is the build system -used to compile Cantera. The description of how to build a project is contained -in a file named ``SConstruct``. The ``SConstruct`` file is actually a Python -script, which makes it very straightforward to add functionality to a -SCons-based build system. - -A typical ``SConstruct`` file for compiling a program that uses Cantera might -look like this: - -.. code:: python - - env = Environment() - - env.Append(CCFLAGS='-g -std=c++17', - CPPPATH=['/usr/local/cantera/include'], - LIBS=['cantera_shared'], - LIBPATH=['/usr/local/cantera/lib'], - RPATH=['/usr/local/cantera/lib'] - LINKFLAGS=['-g', '-pthread']) - - sample = env.Program('sample', 'sample.cpp') - Default(sample) - -This script establishes what SCons refers to as a "construction environment" -named ``env``, and sets the header (``CPPPATH``) and library (``LIBPATH``) paths -to include the directories containing the Cantera headers and libraries. Then, -a program named ``sample`` is compiled using the single source file ``sample.cpp``. - -To determine the appropriate settings for your system, take a look at one of the -pre-configured ``SConstruct`` files that are provided with the C++ examples contained in -the ``samples/cxx`` subdirectory of the Cantera installation directory. - -To build a program using SCons, simply run the following command from a shell in the -directory containing the ``SConstruct`` file: - -.. code:: bash - - scons - -If you installed SCons using Conda, you may need to activate the appropriate Conda -environment so that the ``scons`` command will be on your path. On Windows, you may -need to run this command from a shell with the appropriate Visual Studio environment -variables set. This can be done either by starting the shell using the *Developer -Command Prompt for VS 20xx* shortcut in the Start menu, or by running the batch file: - -.. code:: bat - - C:\Program Files\Visual Studio 2022\VC\Auxiliary\Build\vcvars64.bat - -in an existing shell, where the path specified will depend on the version and -installation path of Visual Studio. - -For more information on SCons, see the `SCons Wiki <https://github.com/SCons/scons/wiki/>`__ -and the `SCons homepage <https://www.scons.org>`__. - -CMake -===== - -CMake is a multi-platform build system that uses a high-level project -description to generate platform-specific build scripts (for example, on Linux, -CMake will generate Makefiles, and on Windows, it can generate Visual Studio ``.sln`` -files). The configuration file for a CMake project is called ``CMakeLists.txt``. A -typical ``CMakeLists.txt`` file for compiling a program that uses Cantera might look -like this: - -.. code:: cmake - - cmake_minimum_required(VERSION 3.1) - project (sample) - - set(CMAKE_VERBOSE_MAKEFILE ON) - set(CMAKE_CXX_STANDARD 17) - - find_package(Threads REQUIRED) - - include_directories("/opt/cantera/include") - link_directories("/opt/cantera/lib") - - add_executable(sample sample.cpp) - target_link_libraries(sample cantera_shared Threads::Threads) - -Several example ``CMakeLists.txt`` files are included with the C++ examples -contained in the ``samples/cxx`` subdirectory of the Cantera installation directory, -which have the paths and lists of libraries correctly configured for the -system on which they are installed. - -To build a program using CMake on Linux or macOS, run the following commands from the -directory containing the ``CMakeLists.txt`` file: - -.. code:: bash - - mkdir build - cd build - cmake .. - cmake --build . - -This will create an executable named ``sample`` in the ``build`` directory. - -To build a program using CMake on Windows, run the following commands from the -directory containing the ``CMakeLists.txt`` file: - -.. code:: bash - - mkdir build - cd build - cmake .. - cmake --build . --config Release - -This will create an executable named ``sample.exe`` in the ``build\Release`` directory. - -Libraries & Library Paths -************************* - -Choosing Libraries During Compilation -===================================== - -Applications can be linked to either the Cantera static library or dynamically linked -to the Cantera shared library. Dynamic linking is recommended generally, and required -to enable features such as the use of ``ExtensibleRate`` objects. The pre-configured -``CMakelists.txt`` and ``SConstruct`` files included with the Cantera examples are set -up to use dynamic linking. - -The Cantera Library -------------------- - -If Cantera was compiled with the ``renamed_shared_libraries=y`` option, then you can -link to the Cantera shared library by specifying the library name ``cantera_shared`` or -to the static library by specifying the library name ``cantera``. If Cantera was -compiled with the ``renamed_shared_libraries=n`` option, then you can link to the shared -library by specifying the library named ``cantera``. - -The ``renamed_shared_libraries=y`` option is the default if you compiled Cantera -yourself, or if you installed packages for Windows. Cantera packages for Conda and -Ubuntu use the setting ``renamed_shared_libraries=n``. - -Additional Dependencies ------------------------ - -If you link to the Cantera shared library, you only need to link to that and any of your -program's direct dependencies. You do not need to link to any of Cantera's dependencies -unless your program also uses them directly. One unexpected direct dependency your -program may have is on the ``fmt`` library, due to its use in C++ templates in Cantera. - -If you link to the Cantera static library, you will also need to specify all of -Cantera's library dependencies when linking your program, as well as the directories -containing these libraries (if they are not in standard search directories). - -Runtime Library Paths -===================== - -Your operating system needs to be able to find the shared library dependencies of your -program when it is run. This process is dependent primarily on your operating system. - -Linux & macOS -------------- - -If you linked to the Cantera shared library, you will need to provide the information -needed to find the Cantera library; the Cantera library then contains the information -needed to find its own dependencies such as SUNDIALS, LAPACK, and yaml-cpp. If you -linked to the Cantera static library, your program depends directly on Cantera's -dependencies instead, and you need to provide the information on where to find these -dependencies when you run your program. - -There are several options for specifying library search paths: - -1. Specify the "rpath" when compiling and linking your program. This is done with the - compiler option for GCC/Clang ``-Wl,-rpath,/path/to/libdir``, where - ``/path/to/libdir`` is the directory containing the Cantera shared library. The build - scripts provided with Cantera's examples are configured to use this option. - -2. If the libraries are installed into a standard system location, such as ``/usr/lib`` - or ``/usr/local/lib`` on Linux, they should be found automatically. - -3. Set the ``LD_LIBRARY_PATH`` (Linux) or ``DYLD_LIBRARY_PATH`` (macOS) environment - variable before running your program. For example, on Linux, use the command: - -.. code:: bash - - export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/libdir - -Windows -------- - -On Windows, all shared library (DLL) dependencies need to be on the ``PATH``. You can -add the Cantera library directory to the ``PATH`` temporarily, for a single command -prompt session, by running a command like: - -.. code:: bat - - set PATH=%PATH%;C:\Program Files\Cantera\bin - -where the path added depends on where you installed Cantera. - -.. container:: container - - .. container:: row - - .. container:: col-4 text-center offset-4 - - .. container:: btn btn-primary - :tagname: a - :attributes: href=index.html - - Return: C++ Interface Tutorial - - .. container:: col-4 text-right - - .. container:: btn btn-primary - :tagname: a - :attributes: href=headers.html - - Next: C++ Header Files diff --git a/pages/tutorials/cxx-guide/demo1a.cpp b/pages/tutorials/cxx-guide/demo1a.cpp deleted file mode 100644 index 79bcf3850..000000000 --- a/pages/tutorials/cxx-guide/demo1a.cpp +++ /dev/null @@ -1,34 +0,0 @@ -#include "cantera/core.h" -#include <iostream> - -using namespace Cantera; - -// The actual code is put into a function that can be called from the main program. -void simple_demo() -{ - // Create a new Solution object - auto sol = newSolution("h2o2.yaml"); - auto gas = sol->thermo(); - - // Set the thermodynamic state by specifying T (500 K) P (2 atm) and the mole - // fractions. Note that the mole fractions do not need to sum to 1.0 - they will - // be normalized internally. Also, the values for any unspecified species will be - // set to zero. - gas->setState_TPX(500.0, 2.0*OneAtm, "H2O:1.0, H2:8.0, AR:1.0"); - - // Print a summary report of the state of the gas. - std::cout << gas->report() << std::endl; -} - -// The main program just calls function simple_demo within a 'try' block, and catches -// CanteraError exceptions that might be thrown. -int main() -{ - try { - simple_demo(); - } catch (CanteraError& err) { - std::cout << err.what() << std::endl; - return 1; - } - return 0; -} diff --git a/pages/tutorials/cxx-guide/demoequil.cpp b/pages/tutorials/cxx-guide/demoequil.cpp deleted file mode 100644 index 0c43b07b2..000000000 --- a/pages/tutorials/cxx-guide/demoequil.cpp +++ /dev/null @@ -1,26 +0,0 @@ -#include "cantera/core.h" -#include <iostream> - -using namespace Cantera; - -void equil_demo() -{ - // Create a new Solution object - auto sol = newSolution("h2o2.yaml"); - auto gas = sol->thermo(); - - gas->setState_TPX(1500.0, 2.0*OneAtm, "O2:1.0, H2:3.0, AR:1.0"); - gas->equilibrate("TP"); - std::cout << gas->report() << std::endl; -} - -int main() -{ - try { - equil_demo(); - } catch (CanteraError& err) { - std::cout << err.what() << std::endl; - return 1; - } - return 0; -} diff --git a/pages/tutorials/cxx-guide/equil-example.rst b/pages/tutorials/cxx-guide/equil-example.rst deleted file mode 100644 index 60f1a83e4..000000000 --- a/pages/tutorials/cxx-guide/equil-example.rst +++ /dev/null @@ -1,102 +0,0 @@ -.. title: Chemical Equilibrium Example Program -.. has_math: true - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Chemical Equilibrium Example Program</h1> - - .. class:: lead - - Learn how to set a phase to a state of chemical equilibrium - - -In the program below, the ``equilibrate`` method is called to set the gas to a -state of chemical equilibrium, holding the temperature and pressure fixed. - -.. include:: pages/tutorials/cxx-guide/demoequil.cpp - :code: c++ - -The program output is:: - - ohmech: - - temperature 1500 K - pressure 2.0265e+05 Pa - density 0.31683 kg/m^3 - mean mol. weight 19.499 kg/kmol - phase of matter gas - - 1 kg 1 kmol - --------------- --------------- - enthalpy -4.1789e+06 -8.1485e+07 J - internal energy -4.8186e+06 -9.3957e+07 J - entropy 11283 2.2001e+05 J/K - Gibbs function -2.1104e+07 -4.115e+08 J - heat capacity c_p 1893 36912 J/K - heat capacity c_v 1466.6 28597 J/K - - mass frac. Y mole frac. X chem. pot. / RT - --------------- --------------- --------------- - H2 0.025847 0.25 -19.295 - H 3.2181e-07 6.2252e-06 -9.6477 - O 6.2927e-12 7.6693e-12 -26.377 - O2 1.1747e-11 7.1586e-12 -52.753 - OH 3.0994e-07 3.5535e-07 -36.024 - H2O 0.46195 0.5 -45.672 - HO2 1.2362e-14 7.3034e-15 -62.401 - H2O2 6.904e-13 3.9578e-13 -72.049 - AR 0.51221 0.25 -21.339 - N2 0 0 - - -How can we tell that this is really a state of chemical equilibrium? Well, by -applying the equation of reaction equilibrium to formation reactions from the -elements, it is straightforward to show that: - -.. math:: - - \mu_k = \sum_m \lambda_m a_{km}. - -where :math:`\mu_k` is the chemical potential of species :math:`k`, :math:`a_{km}` is -the number of atoms of element :math:`m` in species :math:`k`, and :math:`\lambda_m` is the -chemical potential of the elemental species per atom (the so-called "element -potential"). In other words, the chemical potential of each species in an -equilibrium state is a linear sum of contributions from each atom. We see that -this is true in the output above—the chemical potential of H2 is exactly -twice that of H, the chemical potential for OH is the sum of the values for H -and O, the value for H2O2 is twice as large as the value for OH, and so on. - -We'll see later how the ``equilibrate`` function really works. - -.. container:: container - - .. container:: row - - .. container:: col-lg-4 text-left - - .. container:: btn btn-primary - :tagname: a - :attributes: href=thermo.html - title="Computing Thermodynamic Properties" - - Previous: Computing Thermodynamic Properties - - .. container:: col-lg-4 text-center - - .. container:: btn btn-primary - :tagname: a - :attributes: href=index.html - title="C++ Interface Tutorial" - - Return: C++ Interface Tutorial - - .. container:: col-lg-4 text-right - - .. container:: btn btn-primary - :tagname: a - :attributes: href=kinetics-transport.html - title="Reaction Rates and Transport Properties" - - Next: Reaction Rates and Transport Properties diff --git a/pages/tutorials/cxx-guide/headers.rst b/pages/tutorials/cxx-guide/headers.rst deleted file mode 100644 index 335cc0d75..000000000 --- a/pages/tutorials/cxx-guide/headers.rst +++ /dev/null @@ -1,79 +0,0 @@ -.. title: C++ Header Files - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">C++ Header Files</h1> - - .. class:: lead - - Cantera provides some header files designed for use in C++ application - programs. These are designed to include those portions of Cantera needed for - particular types of calculations. - -These headers are designed for use in C++ application programs, and are not -included by the Cantera core. The headers and their functions are: - - -* ``core.h`` - Base classes and functions for creating - `Solution <{{% ct_docs doxygen/html/d5/d40/classCantera_1_1Solution.html %}}>`__ - objects from input files, as well as associated classes defining a phase - *(New in Cantera 3.0)*. - -* ``zerodim.h`` - Zero-dimensional reactor networks. - -* ``onedim.h`` - One-dimensional reacting flows. - -* ``reactionpaths.h`` - Reaction path diagrams. - -* ``thermo.h`` - Base thermodynamic classes and functions for creating - `ThermoPhase <{{% ct_docs doxygen/html/dc/d38/classCantera_1_1ThermoPhase.html %}}>`__ - objects from input files *(Superseded by* ``core.h`` *in Cantera 3.0)*. - -* ``kinetics.h`` - Base kinetics classes and functions for creating - `Kinetics <{{% ct_docs doxygen/html/d4/dc4/classCantera_1_1Kinetics.html %}}>`__ objects from - input files *(Superseded by* ``core.h`` *in Cantera 3.0)*. - -* ``transport.h`` - Base transport property classes and functions for creating - `Transport <{{% ct_docs doxygen/html/d2/dfb/classCantera_1_1Transport.html %}}>`__ - objects from input files *(Superseded by* ``core.h`` *in Cantera 3.0)*. - - -.. container:: container - - .. container:: row - - .. container:: col-4 text-left - - .. container:: btn btn-primary - :tagname: a - :attributes: href=compiling.html - title="Compiling Cantera C++ Applications" - - Previous: Compiling Cantera C++ Applications - - .. container:: col-4 text-center - - .. container:: btn btn-primary - :tagname: a - :attributes: href=index.html - title="C++ Interface Tutorial" - - Return: C++ Interface Tutorial - - .. container:: col-4 text-right - - .. container:: btn btn-primary - :tagname: a - :attributes: href=simple-example.html - title="A Very Simple C++ Program" - - Next: A Very Simple C++ Program diff --git a/pages/tutorials/cxx-guide/index.rst b/pages/tutorials/cxx-guide/index.rst deleted file mode 100644 index 24bf78e6e..000000000 --- a/pages/tutorials/cxx-guide/index.rst +++ /dev/null @@ -1,133 +0,0 @@ -.. title: C++ Interface Tutorial - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">C++ Interface Tutorial</h1> - - .. class:: lead - - This guide shows the basics of using the C++ interface - -.. container:: container - - .. row:: - - .. container:: col-12 - - .. container:: card-deck - - .. container:: card - - .. container:: - :tagname: a - :attributes: href=compiling.html - title="Compiling Cantera C++ Applications" - - .. container:: card-header section-card - - Compiling Cantera C++ Applications - - .. container:: card-body - - .. class:: card-text - - Instructions to compile C++ applications that use Cantera using a - variety of build systems, including CMake, SCons, etc. - - .. container:: card - - .. container:: - :tagname: a - :attributes: href=headers.html - title="Cantera C++ Header Files" - - .. container:: card-header section-card - - Cantera C++ Header Files - - .. container:: card-body - - .. class:: card-text - - Information about the header files used to include Cantera functionality in your C++ - application. - - .. container:: card - - .. container:: - :tagname: a - :attributes: href=simple-example.html - title="A Very Simple C++ Program" - - .. container:: card-header section-card - - A Very Simple C++ Program - - .. container:: card-body - - .. class:: card-text - - A simple example of a C++ program including error handling - - .. row:: - - .. container:: col-12 - - .. container:: card-deck - - .. container:: card - - .. container:: - :tagname: a - :attributes: href=thermo.html - title="Computing Thermodynamic Properties" - - .. container:: card-header section-card - - Computing Thermodynamic Properties - - .. container:: card-body - - .. class:: card-text - - An example demonstrating the calculation of various thermodynamic properties associated - with a particular phase of a substance. - - .. container:: card - - .. container:: - :tagname: a - :attributes: href=equil-example.html - title="Chemical Equilibrium Example Program" - - .. container:: card-header section-card - - Chemical Equilibrium Example Program - - .. container:: card-body - - .. class:: card-text - - An example using the built-in equilibration algorithms to compute the chemical - equilibrium of a mixture. - - .. container:: card - - .. container:: - :tagname: a - :attributes: href=kinetics-transport.html - title="Reaction Rates and Transport Properties" - - .. container:: card-header section-card - - Reaction Rates and Transport Properties - - .. container:: card-body - - .. class:: card-text - - An example using the ``Kinetics`` and ``Transport`` objects - associated with a ``Solution`` object to compute reaction rates, - viscosity, and thermal conductivity. diff --git a/pages/tutorials/cxx-guide/kinetics-transport.rst b/pages/tutorials/cxx-guide/kinetics-transport.rst deleted file mode 100644 index 91df57d1b..000000000 --- a/pages/tutorials/cxx-guide/kinetics-transport.rst +++ /dev/null @@ -1,77 +0,0 @@ -.. title: Computing Reaction Rates and Transport Properties in C++ - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Computing Reaction Rates and Transport Properties in C++</h1> - - .. class:: lead - - Learn how to use ``Kinetics`` and ``Transport`` objects to calculate reaction - rates and transport properties for a phase. - -The following program demonstrates the general method for accessing the following -object types from a ``Solution`` object: - -- ``ThermoPhase``: Represents the thermodynamic properties of mixtures containing one or - more species. Accessed using the ``thermo()`` method on the ``Solution`` object. -- ``Kinetics``: Represents a kinetic mechanism involving one or more phases. Accessed - using the ``kinetics()`` method on the ``Solution`` object. -- ``Transport``: Computes transport properties for a ``ThermoPhase``. Accessed using the - ``transport()`` method on the ``Solution`` object. - -.. include:: pages/tutorials/cxx-guide/kinetics_transport.cpp - :code: c++ - -This program produces the output below:: - - Net reaction rates for reactions involving CO2 - 11 CO + O (+M) <=> CO2 (+M) 3.54150687e-08 - 13 HCO + O <=> CO2 + H 1.95679990e-11 - 29 CH2CO + O <=> CH2 + CO2 3.45366954e-17 - 30 CO + O2 <=> CO2 + O 2.70102741e-13 - 98 CO + OH <=> CO2 + H 6.46935827e-03 - 119 CO + HO2 <=> CO2 + OH 1.86807592e-10 - 131 CH + CO2 <=> CO + HCO 9.41365868e-14 - 151 CH2(S) + CO2 <=> CH2 + CO2 3.11161343e-12 - 152 CH2(S) + CO2 <=> CH2O + CO 2.85339294e-11 - 225 NCO + O2 <=> CO2 + NO 3.74127381e-19 - 228 NCO + NO <=> CO2 + N2 6.25672710e-14 - 261 HNCO + O <=> CO2 + NH 6.84524918e-13 - 267 HNCO + OH <=> CO2 + NH2 7.78871222e-10 - 279 CO2 + NH <=> CO + HNO -3.30333709e-09 - 281 NCO + NO2 <=> CO2 + N2O 2.14286657e-20 - 282 CO2 + N <=> CO + NO 6.42658345e-10 - 289 CH2 + O2 => CO2 + 2 H 1.51032305e-18 - 304 CH2CHO + O => CH2 + CO2 + H 1.00331721e-19 - - T viscosity thermal conductivity - ------ ----------- -------------------- - 300.0 1.6701e-05 4.2143e-02 - 400.0 2.0896e-05 5.2797e-02 - 500.0 2.4704e-05 6.2827e-02 - 600.0 2.8230e-05 7.2625e-02 - 700.0 3.1536e-05 8.2311e-02 - -.. container:: container - - .. container:: row - - .. container:: col-4 text-left - - .. container:: btn btn-primary - :tagname: a - :attributes: href=equil-example.html - title="Equilibrium Example Program" - - Previous: Equilibrium Example Program - - .. container:: col-4 text-center - - .. container:: btn btn-primary - :tagname: a - :attributes: href=index.html - title="C++ Interface Tutorial" - - Return: C++ Interface Tutorial diff --git a/pages/tutorials/cxx-guide/kinetics_transport.cpp b/pages/tutorials/cxx-guide/kinetics_transport.cpp deleted file mode 100644 index edd6e318b..000000000 --- a/pages/tutorials/cxx-guide/kinetics_transport.cpp +++ /dev/null @@ -1,66 +0,0 @@ -#include "cantera/core.h" -#include "cantera/kinetics/Reaction.h" -#include <iostream> - -using namespace Cantera; - -// The actual code is put into a function that can be called from the main program. -void simple_demo2() -{ - // Create a new 'Solution' object that provides access to ThermoPhase, Kinetics and - // Transport objects. - auto sol = newSolution("gri30.yaml", "gri30"); - - // Access the ThermoPhase object. Based on the phase definition in the input file, - // this will reference an IdealGasPhase object. - auto gas = sol->thermo(); - - // Access the Kinetics object. Based on the phase definition in the input file, - // this will reference a GasKinetics object. - auto kin = sol->kinetics(); - - // Set an "interesting" state where we will observe non-zero reaction rates. - gas->setState_TPX(500.0, 2.0*OneAtm, "CH4:1.0, O2:1.0, N2:3.76"); - gas->equilibrate("HP"); - gas->setState_TP(gas->temperature() - 100, gas->pressure()); - - // Get the net reaction rates. - vector_fp wdot(kin->nReactions()); - kin->getNetRatesOfProgress(wdot.data()); - - writelog("Net reaction rates for reactions involving CO2\n"); - size_t kCO2 = gas->speciesIndex("CO2"); - for (size_t i = 0; i < kin->nReactions(); i++) { - if (kin->reactantStoichCoeff(kCO2, i) || kin->productStoichCoeff(kCO2, i)) { - auto rxn = kin->reaction(i); - writelog("{:3d} {:30s} {: .8e}\n", i, rxn->equation(), wdot[i]); - } - } - writelog("\n"); - - // Access the Transport object. Based on the phase definition in the input file, - // this will reference a MixTransport object. - auto trans = sol->transport(); - writelog("T viscosity thermal conductivity\n"); - writelog("------ ----------- --------------------\n"); - for (size_t n = 0; n < 5; n++) { - double T = 300 + 100 * n; - gas->setState_TP(T, gas->pressure()); - writelog("{:.1f} {:.4e} {:.4e}\n", - T, trans->viscosity(), trans->thermalConductivity()); - } -} - -// the main program just calls function simple_demo2 within a 'try' block, and -// catches exceptions that might be thrown -int main() -{ - try { - simple_demo2(); - } catch (std::exception& err) { - std::cout << err.what() << std::endl; - return 1; - } - return 0; -} - diff --git a/pages/tutorials/cxx-guide/simple-example.rst b/pages/tutorials/cxx-guide/simple-example.rst deleted file mode 100644 index 0f29227ab..000000000 --- a/pages/tutorials/cxx-guide/simple-example.rst +++ /dev/null @@ -1,122 +0,0 @@ -.. title: A Very Simple C++ Program - -.. _sec-cxx-simple-example: - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">A Very Simple C++ Program</h1> - - .. class:: lead - - How to build a simple C++ program using Cantera objects - -A short C++ program that uses Cantera is shown below. This program reads in a -specification of a gas mixture from an input file, and then builds a new object -representing the mixture. It then sets the thermodynamic state and composition -of the gas mixture, and prints out a summary of its properties. - -.. include:: pages/tutorials/cxx-guide/demo1a.cpp - :code: c++ - -Before you can run this program, it first needs to be compiled. On a Linux -system using the GCC compiler, a typical command line for compiling this program -might look like this: - -.. code:: bash - - g++ combustor.cpp -o combustor -O3 $(pkg-config --cflags --libs cantera) - -This example relies on the `pkg-config` tool to determine the appropriate compiler -flags, such as those specifying the Cantera header and library files. For more advanced -and flexible methods of compiling programs that use the Cantera C++ library, see -:doc:`compiling`. - -This program produces the output below:: - - ohmech: - - temperature 500 K - pressure 2.0265e+05 Pa - density 0.36118 kg/m^3 - mean mol. weight 7.4093 kg/kmol - phase of matter gas - - 1 kg 1 kmol - --------------- --------------- - enthalpy -2.4772e+06 -1.8354e+07 J - internal energy -3.0382e+06 -2.2511e+07 J - entropy 20699 1.5337e+05 J/K - Gibbs function -1.2827e+07 -9.5038e+07 J - heat capacity c_p 3919.1 29038 J/K - heat capacity c_v 2797 20724 J/K - - mass frac. Y mole frac. X chem. pot. / RT - --------------- --------------- --------------- - H2 0.21767 0.8 -15.644 - H 0 0 - O 0 0 - O2 0 0 - OH 0 0 - H2O 0.24314 0.1 -82.953 - HO2 0 0 - H2O2 0 0 - AR 0.53919 0.1 -20.503 - N2 0 0 - -As C++ programs go, this one is *very* short. It is the Cantera equivalent of -the "Hello, World" program most programming textbooks begin with. But it -illustrates some important points in writing Cantera C++ programs. - -Catching ``CanteraError`` exceptions -==================================== - -The entire body of the program is put inside a function that is invoked within -a ``try`` block in the main program. In this way, exceptions thrown in the -function or in any procedure it calls may be caught. In this program, a -``catch`` block is defined for exceptions of type `CanteraError`_. Cantera -throws exceptions of this type, so it is always a good idea to catch them. - -The ``report`` function -======================= - -The `ThermoPhase.report`_ function generates a nicely-formatted report of the properties of -a phase, including its composition in both mole (X) and mass (Y) units. For -each species present, the non-dimensional chemical potential is also printed. -This is handy particularly when doing equilibrium calculations. This function -is very useful to see at a glance the state of some phase. - -.. _CanteraError: {{% ct_docs doxygen/html/db/ddf/classCantera_1_1CanteraError.html %}} -.. _ThermoPhase.report: {{% ct_docs doxygen/html/dc/d38/classCantera_1_1ThermoPhase.html#a046799f2a038fddf13b5752cd0cc7117 %}} - -.. container:: container - - .. container:: row - - .. container:: col-4 text-left - - .. container:: btn btn-primary - :tagname: a - :attributes: href=headers.html - title="C++ Header Files" - - Previous: C++ Header Files - - .. container:: col-4 text-center - - .. container:: btn btn-primary - :tagname: a - :attributes: href=index.html - title="C++ Interface Tutorial" - - Return: C++ Interface Tutorial - - .. container:: col-4 text-right - - .. container:: btn btn-primary - :tagname: a - :attributes: href=thermo.html - title="Computing Properties" - - Next: Computing Properties diff --git a/pages/tutorials/cxx-guide/thermo.rst b/pages/tutorials/cxx-guide/thermo.rst deleted file mode 100644 index 4ed6ce8a9..000000000 --- a/pages/tutorials/cxx-guide/thermo.rst +++ /dev/null @@ -1,163 +0,0 @@ -.. title: Computing Thermodynamic Properties -.. has_math: true - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Computing Thermodynamic Properties<h1> - - .. class:: lead - - Demonstration of how to use Cantera to compute thermodynamic properties of a phase - -Class ThermoPhase -================= - -Cantera can be used to compute thermodynamic properties of pure substances, -solutions, and mixtures of various types, including ones containing multiple -phases. The first step is to create an object that represents each phase. A -simple, complete program that creates an object representing a gas mixture and -prints its temperature is shown below: - -.. include:: pages/tutorials/cxx-guide/thermobasic.cpp - :code: c++ - -Here, ``newSolution`` imports all information held by a YAML input file into a Cantera -`Solution`_ object, which is accessed by the pointer ``sol``. The thermodynamic -information is accessible via ``sol->thermo()``, which itself returns a pointer to -a `ThermoPhase`_ object. - -Class `ThermoPhase`_ is the base class for Cantera classes that represent -phases of matter. It defines the public interface for all classes that represent -phases. For example, it specifies that they all have a method ``temperature`` -that returns the current temperature, a method -``setTemperature(double T)`` that sets the -temperature, a method ``getChemPotentials(double* mu)`` that writes the species chemical potentials -into array ``mu``, and so on. - -Class `ThermoPhase`_ can be used to represent the intensive state of any -single-phase solution of multiple species. The phase may be a bulk, -three-dimensional phase (a gas, a liquid, or a solid), or it may be a -two-dimensional surface phase, or even a one-dimensional "edge" phase. The -specific attributes of each type of phase are specified by deriving a class from -`ThermoPhase`_ and providing implementations for its virtual methods. - -Cantera has a wide variety of models for bulk phases currently. Special attention -(in terms of the speed of execution) has been paid to an ideal gas phase -implementation, where the species thermodynamic polynomial representations -adhere to either the NASA polynomial form or the Shomate polynomial -form. This is widely used in combustion applications, the original application -that Cantera was designed for. Recently, a lot of effort has been placed into -constructing non-ideal liquid phase thermodynamics models that are used in -electrochemistry and battery applications. These models include a Pitzer -implementation for brines solutions and a Margules excess Gibbs free energy -implementation for molten salts. - -The Intensive Thermodynamic State ---------------------------------- - -Class `ThermoPhase`_ and classes derived from it work only with the intensive -thermodynamic state. That is, all extensive properties (enthalpy, entropy, -internal energy, volume, etc.) are computed for a unit quantity (on a mass or -mole basis). For example, there is a method ``enthalpy_mole()`` that returns -the molar enthalpy (J/kmol), and a method ``enthalpy_mass()`` that returns the -specific enthalpy (J/kg), but no method *enthalpy()* that would return the total -enthalpy (J). This is because class `ThermoPhase`_ does not store the total amount -(mass or mole) of the phase. - -The intensive state of a single-component phase in equilibrium is fully -specified by the values of any :math:`r+1` independent thermodynamic properties, -where :math:`r` is the number of reversible work modes. If the only reversible -work mode is compression (a "simple compressible substance"), then two -properties suffice to specify the intensive state. Class `ThermoPhase`_ stores -internally the values of the *temperature*, the *mass density*, and the *mass -fractions* of all species. These values are sufficient to fix the intensive -thermodynamic state of the phase, and to compute any other intensive properties. -This choice is arbitrary, and for most purposes you can't tell which properties -are stored and which are computed. - -Derived Classes ---------------- - -Many of the methods of `ThermoPhase`_ are declared virtual, and are meant to be -overloaded in classes derived from ThermoPhase. For example, class -`IdealGasPhase`_ derives from `ThermoPhase`_, and represents ideal gas -mixtures. - -Although class `ThermoPhase`_ defines the interface for all classes representing -phases, it only provides implementations for a few of the methods. This is -because `ThermoPhase`_ does not actually know the equation of state of any -phase—this information is provided by classes that derive from `ThermoPhase`_. -The methods implemented by `ThermoPhase`_ are ones that apply to all phases, -independent of the equation of state. For example, it implements methods -``temperature()`` and ``setTemperature()``, since the temperature value is -stored internally. - -* `Classes that inherit from ThermoPhase <{{% ct_docs doxygen/html/dd/db1/group__thermoprops.html %}}>`__ -* `Classes that handle standard states for species <{{% ct_docs doxygen/html/d1/de1/group__spthermo.html %}}>`__ - -Example Program -=============== - -In the program below, a gas mixture object is created, and a few thermodynamic -properties are computed and printed out: - -.. include:: pages/tutorials/cxx-guide/thermodemo.cpp - :code: c++ - -Note that the methods that compute the properties take no input parameters. The -properties are computed for the state that has been previously set and stored -internally within the object. - -Naming Conventions ------------------- - -- methods that return *molar* properties have names that end in ``_mole``. -- methods that return properties *per unit mass* have names that end in - ``_mass``. -- methods that write an array of values into a supplied output array have names - that begin with ``get``. For example, the method - ``getChemPotentials(double* mu)`` writes the species chemical - potentials into the output array ``mu``. - -The thermodynamic property methods are declared in class `ThermoPhase`_, -which is the base class from which all classes that represent any type of phase -of matter derive. - -See `ThermoPhase`_ for the full list of available thermodynamic properties. - -.. _Solution: {{% ct_docs doxygen/html/d5/d40/classCantera_1_1Solution.html %}} -.. _ThermoPhase: {{% ct_docs doxygen/html/dc/d38/classCantera_1_1ThermoPhase.html %}} -.. _IdealGasPhase: {{% ct_docs doxygen/html/d7/dfa/classCantera_1_1IdealGasPhase.html %}} - -.. container:: container - - .. container:: row - - .. container:: col-4 text-left - - .. container:: btn btn-primary - :tagname: a - :attributes: href=simple-example.html - title="A Very Simple C++ Program" - - Previous: A Very Simple C++ Program - - .. container:: col-4 text-center - - .. container:: btn btn-primary - :tagname: a - :attributes: href=index.html - title="C++ Interface Tutorial" - - Return: C++ Interface Tutorial - - .. container:: col-4 text-right - - .. container:: btn btn-primary - :tagname: a - :attributes: href=equil-example.html - title="Equilibrium Example Program" - - Next: Equilibrium Example Program diff --git a/pages/tutorials/cxx-guide/thermobasic.cpp b/pages/tutorials/cxx-guide/thermobasic.cpp deleted file mode 100644 index 5faab70e1..000000000 --- a/pages/tutorials/cxx-guide/thermobasic.cpp +++ /dev/null @@ -1,12 +0,0 @@ -#include "cantera/core.h" -#include <iostream> - -int main(int argc, char** argv) -{ - // Create a new Solution object - auto sol = Cantera::newSolution("h2o2.yaml"); - auto gas = sol->thermo(); - - std::cout << gas->temperature() << std::endl; - return 0; -} diff --git a/pages/tutorials/cxx-guide/thermodemo.cpp b/pages/tutorials/cxx-guide/thermodemo.cpp deleted file mode 100644 index 92451e899..000000000 --- a/pages/tutorials/cxx-guide/thermodemo.cpp +++ /dev/null @@ -1,45 +0,0 @@ -#include "cantera/core.h" -#include <iostream> - -using namespace Cantera; - -void thermo_demo(const std::string& file, const std::string& phase) -{ - // Create a new Solution object - auto sol = newSolution(file, phase); - auto gas = sol->thermo(); - - gas->setState_TPX(1500.0, 2.0*OneAtm, "O2:1.0, H2:3.0, AR:1.0"); - - // temperature, pressure, and density - std::cout << gas->temperature() << std::endl; - std::cout << gas->pressure() << std::endl; - std::cout << gas->density() << std::endl; - - // molar thermodynamic properties - std::cout << gas->enthalpy_mole() << std::endl; - std::cout << gas->entropy_mole() << std::endl; - - // specific (per unit mass) thermodynamic properties - std::cout << gas->enthalpy_mass() << std::endl; - std::cout << gas->entropy_mass() << std::endl; - - // chemical potentials of the species - size_t numSpecies = gas->nSpecies(); - vector_fp mu(numSpecies); - gas->getChemPotentials(mu.data()); - for (size_t n = 0; n < numSpecies; n++) { - std::cout << gas->speciesName(n) << " " << mu[n] << std::endl; - } -} - -int main(int argc, char** argv) -{ - try { - thermo_demo("h2o2.yaml", "ohmech"); - } catch (CanteraError& err) { - std::cout << err.what() << std::endl; - return 1; - } - return 0; -} diff --git a/pages/tutorials/index.rst b/pages/tutorials/index.rst deleted file mode 100644 index 4bd514c6d..000000000 --- a/pages/tutorials/index.rst +++ /dev/null @@ -1,166 +0,0 @@ -.. title: Tutorials -.. date: 2018-05-30 11:20:56 UTC-04:00 -.. description: Cantera Tutorial page -.. type: text - -.. container:: jumbotron - - .. raw:: html - - <h1 class="display-4">Getting started with Cantera</h1> - - .. class:: lead - - For those new to Cantera, we present here a set of short - tutorials to familiarize you with Cantera's basic functionality and basic - capabilities, give some examples of how to work Cantera within your preferred - interface language—basic function calls and a few simple applications—and - demonstrate some basic troubleshooting. - -After installing Cantera and finishing these tutorials, you should be -ready to begin using Cantera. The next steps, linked below the tutorials, -provide information in this regard. - -First, let's pick an interface language and get started with the -tutorials. Note that while Cantera can be accessed via other interfaces -(namely Fortran and directly in C++), Python and Matlab present the most -convenient interfaces for learning about Cantera, and are the interface of -preference for the vast majority of Cantera users. - -.. container:: card-deck - - .. container:: card - - .. container:: - :tagname: a - :attributes: href=python-tutorial.html - title=Python - - .. container:: card-header section-card - - Python Tutorial - - .. container:: card-body - - .. container:: card-text - - I want to learn about Cantera via the Python module. - - .. container:: card - - .. container:: - :tagname: a - :attributes: href=matlab-tutorial.html - title=Matlab - - .. container:: card-header section-card - - Matlab Tutorial - - .. container:: card-body - - .. container:: card-text - - I want to learn about Cantera via the Matlab toolbox - - .. container:: card - - .. container:: - :tagname: a - :attributes: href=cxx-guide/index.html - title="C++ Guide" - - .. container:: card-header section-card - - Advanced: C++ Tutorial - - .. container:: card-body - - .. container:: card-text - - I want to learn about Cantera via the C++ interface - -.. jumbotron:: - - .. raw:: html - - <h2 class="display-4" id="cantera-next-steps">Next Steps</h2> - - .. class:: lead - - Okay, so you've finished the tutorials and understand the basic user functionality of Cantera. - Now what? - -Using Cantera for a range of problems will likely require you to extend -your knowledge in two ways: - -- You will need an input file describing the phase(s) of matter - relevant to your problem. -- Your application may very well require function calls and routines - not necessarily covered in the tutorials. - -The links below will help you take the 'next steps,' and point you to: - -- Information on how to locate and work with Cantera input files (which - contain the thermodynamic, transport, and chemical kinetic information - for the phases of interest). -- Detailed documentation and user guides for accessing Cantera via - Python, Matlab, and directly via C++. For advanced and intermediate - users, the documentation is an easily-searchable repository for - information on specific functions of interest. -- A repository of examples, demonstrating how to use Cantera to solve a - diverse range of problems. You can either use these examples directly, - or use them as a template to develop your own applications. - -.. container:: card-deck - - .. container:: card - - .. container:: - :tagname: a - :attributes: href=input-files.html - title="Input Files" - - .. container:: card-header section-card - - Cantera Input Files - - .. container:: card-body - - .. container:: card-text - - Learn how to locate and/or create input files. - - .. container:: card - - .. container:: - :tagname: a - :attributes: href=/documentation/index.html - title="Documentation" - - .. container:: card-header section-card - - Users' Guides and Documentation - - .. container:: card-body - - .. container:: card-text - - Locate documentation on specific Cantera functions. - - .. container:: card - - .. container:: - :tagname: a - :attributes: href=/examples/index.html - title="Documentation" - - .. container:: card-header section-card - - Examples - - .. container:: card-body - - .. container:: card-text - - See examples of Cantera applications diff --git a/pages/tutorials/input-files.rst b/pages/tutorials/input-files.rst deleted file mode 100644 index c67d03943..000000000 --- a/pages/tutorials/input-files.rst +++ /dev/null @@ -1,175 +0,0 @@ -.. title: Input Files -.. description: Cantera Input File Tutorial page -.. type: text - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Working With Input Files</h1> - - .. class:: lead - - As covered in the tutorials (:doc:`Python <python-tutorial>` and :doc:`Matlab - <matlab-tutorial>`), all calculations in Cantera require an input file to describe the - properties of the relevant phase(s) of matter. - -The required input files can be provided via one of several methods: - -- Use one of the pre-existing input files that are distributed with Cantera (note that - these input files are provided for convenience, and may not be suited for research) -- Convert a pre-existing mechanism from Chemkin (CK) format to YAML format *(New - in Cantera 2.5)* -- Create your own YAML file from scratch or by editing an existing file *(New in - Cantera 2.5)* - -The first option will suffice for tutorials and introductory work with thermodynamic -phases and reaction kinetics. Most modern reaction mechanisms are published in Chemkin -(CK) format, and can be converted to Cantera's YAML format using the ``ck2yaml`` -conversion tool (option 2). Advanced users may, however, need to edit an existing input -file in order to define additional species, reactions, or entirely new phases. Even if -you need to create an entirely new input file, it is still advisable to start from an -existing file, to cut down on syntax errors. - -Whenever you edit a Cantera input file, it is *highly advised* that you begin by copying the existing file and -saving it under a new name, before editing the new file. Editing a file under its original name can -easily lead to errors, if one forgets that this file does not represent the original mechanism. - -Input files distributed with Cantera -==================================== - -Several reaction mechanism files are included in the Cantera distribution, -including ones that model natural gas combustion (``gri30.yaml``), high-temperature air -(``air.yaml``), a hydrogen/oxygen reaction mechanism (``h2o2.yaml``), some pure fluids in the -liquid-vapor region (``liquidvapor.yaml``), and a few surface reaction mechanisms (such as -``ptcombust.yaml``, ``diamond.yaml``, etc.), among others. Under Windows, these files may be located -in ``C:\Program Files\Cantera\data`` depending on how you installed Cantera and the options you -specified. On a Unix/Linux/macOS machine, they are usually kept in the ``data`` subdirectory -within the Cantera installation directory. You can also browse the -`list of data files <https://github.com/Cantera/cantera/tree/main/data>`__ in the -Cantera source repository. - -Please see the tutorials for :doc:`Python <python-tutorial>` and :doc:`Matlab <matlab-tutorial>` -for instructions on how to import from these pre-existing files. - -Converting or Creating New Input Files -====================================== - -If you want to model a phase not available in the input files distributed with Cantera, you will need -to either procure a new input file (there are a limited number of input files available on the web), or -create a new one. - -There are several options for creating a new Cantera input file: - -.. container:: container - - .. row:: - - .. container:: card-deck - - .. container:: card - - .. container:: - :tagname: a - :attributes: href=ck2yaml-tutorial.html - title="Chemkin File Conversion" - - .. container:: card-header section-card - - Conversion from Chemkin to YAML - - .. container:: card-body - - .. container:: card-text - - Convert a Chemkin-formatted ('CK') file to the Cantera YAML - format. *(New in Cantera 2.5)* - - .. container:: card - - .. container:: - :tagname: a - :attributes: href="yaml/defining-phases.html" - title="Defining Phases in YAML" - - .. container:: card-header section-card - - Create a new YAML file - - .. container:: card-body - - .. container:: card-text - - Create a completely new mechanism, by defining new species, - phases, and/or reactions, using the YAML format. - *(New in Cantera 2.5)* - - .. row:: - - .. container:: card-deck - - .. container:: card - - .. container:: - :tagname: a - :attributes: href="legacy2yaml.html" - title="Converting CTI and XML input files to YAML" - - .. container:: card-header section-card - - Convert CTI and XML input files to YAML - - .. container:: card-body - - .. container:: card-text - - Convert existing Cantera mechanisms in the legacy CTI or XML - formats to the YAML format. *(New in Cantera 2.5)* - - .. container:: card - - .. container:: - :tagname: a - :attributes: href="thermobuild.html" - title="Importing data from NASA ThermoBuild" - - .. container:: card-header section-card - - Importing data from NASA ThermoBuild - - .. container:: card-body - - .. container:: card-text - - Import thermodynamic data for a range of species from this - web-based tool. - -Understanding Input File Syntax -=============================== - -For any of these options (adapting an existing Cantera input file, converting from CK, or creating a new input -file), it can be helpful to understand the input file syntax requirements. Clearly, anyone writing directly -in the YAML formats must conform to these standards. However, even when importing an -externally-provided file or converting from CK format, understanding the input file syntax can -help diagnose and correct any errors (although many/most of the CK conversion errors will be related -to errors in the CK syntax formatting). - -.. container:: card-deck - - .. container:: card - - .. container:: - :tagname: a - :attributes: href="yaml/yaml-format.html" - title="YAML Format Tutorial" - - .. container:: card-header section-card - - YAML Format Tutorial - - .. container:: card-body - - .. container:: card-text - - This tutorial covers the details of the YAML format and its syntax. - *(New in Cantera 2.5)* diff --git a/pages/tutorials/legacy2yaml-tutorial.rst b/pages/tutorials/legacy2yaml-tutorial.rst deleted file mode 100644 index 3a71b4419..000000000 --- a/pages/tutorials/legacy2yaml-tutorial.rst +++ /dev/null @@ -1,95 +0,0 @@ -.. title: Converting CTI and XML input files to YAML -.. slug: legacy2yaml -.. has_math: true - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Converting CTI and XML input files to YAML</h1> - - .. class:: lead - - If you want to convert an existing, legacy CTI or XML input file to the - YAML format, this section will help. - -cti2yaml --------- - -Cantera comes with a converter utility ``cti2yaml`` (or ``cti2yaml.py``) that -converts legacy CTI format mechanisms into the new YAML format introduced in -Cantera 2.5. This program can be run from the command line to convert files to -the YAML format. *(New in Cantera 2.5)* - -Usage: - -.. code:: bash - - cti2yaml [-h] input [output] - -The ``input`` argument is required, and specifies the name of the input file to -be converted. The optional ``output`` argument specifies the name of the new -output file. If ``output`` is not specified, then the output file will have the -same name as the input file, with the extension replaced with ``.yaml``. - -Example: - -.. code:: bash - - cti2yaml mymech.cti - -will generate the output file ``mymech.yaml``. - -If the ``cti2yaml`` script is not on your path, but the Cantera Python module -is, ``cti2yaml`` can be used by running: - -.. code:: bash - - python -m cantera.cti2yaml mymech.cti - -It is not necessary to use ``cti2yaml`` to convert any of the CTI input files -previously included with Cantera. YAML versions of these files are already included with -Cantera. - -For input files where you have both the CTI and XML versions, ``cti2yaml`` is -recommended over ``ctml2yaml``. In cases where the mechanism was originally -converted from a CK-format mechanism, it is recommended to use ``ck2yaml`` if -the original input files are available. - -ctml2yaml ---------- - -Cantera comes with a converter utility ``ctml2yaml`` (or ``ctml2yaml.py``) that -converts legacy XML (CTML) format mechanisms into the new YAML format introduced -in Cantera 2.5. This program can be run from the command line to convert files -to the YAML format. *(New in Cantera 2.5)* - -Usage: - -.. code:: bash - - ctml2yaml [-h] input [output] - -The ``input`` argument is required, and specifies the name of the input file to -be converted. The optional ``output`` argument specifies the name of the new -output file. If ``output`` is not specified, then the output file will have the -same name as the input file, with the extension replaced with ``.yaml``. - -Example: - -.. code:: bash - - ctml2yaml mymech.xml - -will generate the output file ``mymech.yaml``. - -If the ``ctml2yaml`` script is not on your path, but the Cantera Python module -is, ``ctml2yaml`` can be used by running: - -.. code:: bash - - python -m cantera.cti2yaml mymech.xml - -It is not necessary to use ``ctml2yaml`` to convert any of the XML input files -included with Cantera. YAML versions of these files are already included with -Cantera. diff --git a/pages/tutorials/thermobuild.rst b/pages/tutorials/thermobuild.rst deleted file mode 100644 index 5e116a4c0..000000000 --- a/pages/tutorials/thermobuild.rst +++ /dev/null @@ -1,126 +0,0 @@ -.. slug: thermobuild -.. title: Using data from NASA ThermoBuild -.. has_math: true -.. _sec-thermobuild: - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Converting Data from NASA ThermoBuild</h1> - -Thermodynamic data for a range of species can be obtained from the -`NASA ThermoBuild <https://cearun.grc.nasa.gov/ThermoBuild/index_ds.html>`__ tool. -This thermodynamic data is described using the -:ref:`9-coefficient NASA polynomial <sec-thermo-nasa9>` parameterization, which is -implemented by Cantera. - -To generate an input file containing thermodynamic data, use the ThermoBuild web -interface to select the elements you want to include, and click *process*. -Then, select the species you want to include in your mechanism and click *continue*. -Select the content on the resulting page starting with the line that says ``thermo``, -and ending with the line that says ``END REACTANTS`` and save it to a file. - -Next, we need to make a few modifications to this file so it contains all of the -information needed to be processed by Cantera's CK file parser. For this example, let's -suppose you have selected just the species ``CO`` and ``CO2`` from ThermoBuild. - -* Modify the first line of the file so that it reads ``thermo nasa9``. This is done to - distinguish this input format from the one used for the 7-coefficient NASA - polynomials. -* Replace the last two lines (``END PRODUCTS`` and ``END REACTANTS``) with a single line - that reads ``END``. - -Creating species definitions only ---------------------------------- - -If you only want to generate a species database that can be referenced from other -Cantera input files, the above modifications are sufficient. The last step is simply -to convert the input file to the Cantera YAML format using ``ck2yaml``. If you named the -file ``mythermo.txt``, then the command to convert it would be: - -.. code:: bash - - ck2yaml --thermo=mythermo.txt - -This will generate the file ``mythermo.yaml``. You can then reference the species -definitions from this file in phase definitions in other Cantera input files, for -example: - -.. code:: yaml - - phases: - - name: gas - thermo: ideal-gas - species: - - {mythermo.yaml/species: all} - -Creating a complete phase definition ------------------------------------- - -To create a complete phase definition, you also need to add two sections to the top of -the ThermoBuild input file: - -- A section declaring all of the elements: - - .. code:: - - elements - C O - end - -- A section declaring all of the species: - - .. code:: - - species - CO CO2 - end - -The resulting input file should look like the following: - -.. code:: - - elements - C O - end - - species - CO CO2 - end - - thermo nasa9 - 200.000 1000.000 6000.000 20000.000 9/09/04 - CO Gurvich,1979 pt1 p25 pt2 p29. - 3 tpis79 C 1.00O 1.00 0.00 0.00 0.00 0 28.0101000 -110535.196 - 200.000 1000.0007 -2.0 -1.0 0.0 1.0 2.0 3.0 4.0 0.0 8671.104 - 1.489045326D+04-2.922285939D+02 5.724527170D+00-8.176235030D-03 1.456903469D-05 - -1.087746302D-08 3.027941827D-12 -1.303131878D+04-7.859241350D+00 - 1000.000 6000.0007 -2.0 -1.0 0.0 1.0 2.0 3.0 4.0 0.0 8671.104 - 4.619197250D+05-1.944704863D+03 5.916714180D+00-5.664282830D-04 1.398814540D-07 - -1.787680361D-11 9.620935570D-16 -2.466261084D+03-1.387413108D+01 - 6000.000 20000.0007 -2.0 -1.0 0.0 1.0 2.0 3.0 4.0 0.0 8671.104 - 8.868662960D+08-7.500377840D+05 2.495474979D+02-3.956351100D-02 3.297772080D-06 - -1.318409933D-10 1.998937948D-15 5.701421130D+06-2.060704786D+03 - CO2 Gurvich,1991 pt1 p27 pt2 p24. - 3 g 9/99 C 1.00O 2.00 0.00 0.00 0.00 0 44.0095000 -393510.000 - 200.000 1000.0007 -2.0 -1.0 0.0 1.0 2.0 3.0 4.0 0.0 9365.469 - 4.943650540D+04-6.264116010D+02 5.301725240D+00 2.503813816D-03-2.127308728D-07 - -7.689988780D-10 2.849677801D-13 -4.528198460D+04-7.048279440D+00 - 1000.000 6000.0007 -2.0 -1.0 0.0 1.0 2.0 3.0 4.0 0.0 9365.469 - 1.176962419D+05-1.788791477D+03 8.291523190D+00-9.223156780D-05 4.863676880D-09 - -1.891053312D-12 6.330036590D-16 -3.908350590D+04-2.652669281D+01 - 6000.000 20000.0007 -2.0 -1.0 0.0 1.0 2.0 3.0 4.0 0.0 9365.469 - -1.544423287D+09 1.016847056D+06-2.561405230D+02 3.369401080D-02-2.181184337D-06 - 6.991420840D-11-8.842351500D-16 -8.043214510D+06 2.254177493D+03 - END - -This file (saved for example as ``myphase.txt``) can then be converted to the Cantera -YAML format using the ``ck2yaml`` script: - -.. code:: bash - - ck2yaml --input=myphase.txt - -This will generate a an input file named ``myphase.yaml`` with a phase named ``gas`` -that can be directly imported in Cantera. diff --git a/pages/tutorials/yaml/defining-phases.rst b/pages/tutorials/yaml/defining-phases.rst deleted file mode 100644 index 2fa8da930..000000000 --- a/pages/tutorials/yaml/defining-phases.rst +++ /dev/null @@ -1,135 +0,0 @@ -.. slug: defining-phases -.. title: Defining Phases - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Defining Phases</h1> - - .. class:: lead - - A guide to Cantera's YAML input file format - -Virtually every Cantera simulation involves one or more phases of matter. -Depending on the calculation being performed, it may be necessary to evaluate -thermodynamic properties, transport properties, and/or reaction rates for the -phase(s) present. Before the properties can be evaluated, each phase must be -defined, meaning that the models to use to compute its properties and reaction -rates must be specified, along with any parameters the models require. - -Because the amount of data required can be quite large, this data is imported -from a YAML file that can be read by the application, so that a given phase -model can be re-used for other simulations. - -This guide describes how to write such files to define phases and interfaces for -use in Cantera simulations. Each link below represents a standalone module - -while you certainly can read them in order, you can also jump to whichever -section addresses your current needs. If you need tips on troubleshooting the -YAML file syntax rules, please look at the :doc:`YAML Format Tutorial <yaml-format>`. - -.. container:: card-deck - - .. container:: card - - .. container:: - :tagname: a - :attributes: href=phases.html - title="Phases and their Interfaces" - - .. container:: card-header section-card - - Phases and their Interfaces - - .. container:: card-body - - .. container:: card-text - - For each phase that appears in a problem, a corresponding entry - should be present in the input file(s). We'll start by describing - the entries for phases of various types, and then look at how to - define interfaces between phases. - - .. container:: card - - .. container:: - :tagname: a - :attributes: href=yaml-species.html - title="Elements and Species" - - .. container:: card-header section-card - - Elements and Species - - .. container:: card-body - - .. container:: card-text - - For each species declared as part of a phase description, both the - species and the elements that it is comprised of must be defined. - Here, we describe how both are defined. - - .. container:: card - - .. container:: - :tagname: a - :attributes: href=reactions.html - title="Reactions" - - .. container:: card-header section-card - - Reactions - - .. container:: card-body - - .. container:: card-text - - Cantera supports a number of different types of reactions, including - several types of homogeneous reactions, surface reactions, and - electrochemical reactions. For each, there is a corresponding entry - type. Here, we describe how to declare each type of reaction and - provide the necessary parameters to calculate the reaction rate for - each. - -Additional Information -====================== - -.. container:: card-deck - - .. container:: card - - .. container:: - :tagname: a - :attributes: href=yaml-format.html - title="YAML Format Tutorial" - - .. container:: card-header section-card - - YAML Format Tutorial - - .. container:: card-body - - .. container:: card-text - - This module describes the basics of the YAML format as used by - Cantera, how dimensional values are represented, and how to - understand error messages that occur while reading input files. - - .. container:: card - - .. container:: - :tagname: a - :attributes: href={{% ct_docs sphinx/html/yaml/index.html %}} - title="YAML Format Reference" - - .. container:: card-header section-card - - YAML Format Reference - - .. container:: card-body - - .. container:: card-text - - The documentation of the YAML format, containing the specification - for each of the entry types discussed previously, for when you - require more detail. diff --git a/pages/tutorials/yaml/phases.rst b/pages/tutorials/yaml/phases.rst deleted file mode 100644 index 468bcfe79..000000000 --- a/pages/tutorials/yaml/phases.rst +++ /dev/null @@ -1,504 +0,0 @@ -.. slug: phases -.. title: Phases and their Interfaces - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Phases and their Interfaces in YAML</h1> - - .. class:: lead - - A description of how phases and interfaces are defined in YAML input files. - -.. TODO: Add link to :ref:`YAML phases <sec-yaml-phases>` once version 2.6 is released - -Phases -====== - -For each phase that appears in a problem, a corresponding entry should be -present in the input file(s). The phase entry specifies the elements and species -present in that phase, and the models to be used for computing thermodynamic, -kinetic, and transport properties. - -Naming the Phase ----------------- - -The ``name`` entry is a string that identifies the phase. It must be unique -within the file among all phase definitions of any type. Phases are referenced -by name when importing them. The ``name`` is also used to identify the phase -within multiphase mixtures or at phase boundaries. - -Setting the Thermodynamic Model -------------------------------- - -The thermodynamic model used to represent a phase is specified in the ``thermo`` -field. Supported models are: - -- :ref:`binary-solution-tabulated <sec-yaml-binary-solution-tabulated>`: A - binary mixture where the excess enthalpy and entropy are interpolated between - tabulated values as a function of mole fraction; *New in Cantera 2.5* -- :ref:`compound-lattice <sec-yaml-compound-lattice>`: A phase that is comprised - of a fixed additive combination of other lattice phases -- :ref:`coverage-dependent-surface <sec-yaml-coverage-dependent-surface>`: A surface - phase where the enthalpy, entropy, and heat capacity of each species may depend on - the species' coverages. *New in Cantera 3.0* -- :ref:`Debye-Huckel <sec-yaml-Debye-Huckel>`: A dilute liquid electrolyte which - obeys the Debye-Hückel formulation for nonideality -- :ref:`edge <sec-yaml-edge>`: A one-dimensional edge between two surfaces -- :ref:`electron-cloud <sec-yaml-electron-cloud>`: A phase representing free - electrons in a metal -- :ref:`fixed-stoichiometry <sec-yaml-fixed-stoichiometry>`: An incompressible, - single-species phase -- :ref:`HMW-electrolyte <sec-yaml-HMW-electrolyte>`: A dilute or concentrated - liquid electrolyte which obeys the Pitzer formulation for nonideality -- :ref:`ideal-gas <sec-yaml-ideal-gas>`: A mixture which obeys the ideal gas law -- :ref:`ideal-molal-solution <sec-yaml-ideal-molal-solution>`: An ideal solution - based on the mixing-rule assumption that all molality-based activity - coefficients are equal to one -- :ref:`ideal-condensed <sec-yaml-ideal-condensed>`: An ideal liquid or solid solution -- :ref:`ideal-solution-VPSS <sec-yaml-ideal-solution-VPSS>`: An ideal solution; - Uses "variable pressure standard state" methods for calculating thermodynamic - properties -- :ref:`ideal-surface <sec-yaml-ideal-surface>`: A surface between two bulk - phases -- :ref:`ions-from-neutral-molecule <sec-yaml-ions-from-neutral-molecule>`: A - phase for representing ionic species based on another phase where those ions - are components of neutral molecules; *Deprecated in Cantera 3.0* -- :ref:`lattice <sec-yaml-lattice>`: A simple model for an incompressible - lattice of solid atoms -- :ref:`liquid-water-IAPWS95 <sec-yaml-liquid-water-IAPWS95>`: An implementation - of the IAPWS95 equation of state for water, for the liquid region only -- :ref:`Margules <sec-yaml-Margules>`: A model that employs the Margules - approximation for the excess Gibbs free energy -- :ref:`Maskell-solid-solution <sec-yaml-Maskell-solid-solution>`: A condensed, - binary, non-ideal solution; *Deprecated in Cantera 3.0* -- :ref:`Peng-Robinson <sec-yaml-Peng-Robinson>`: A multi-species real gas following the - Peng-Robinson equation of state; *New in Cantera 3.0* -- :ref:`plasma <sec-yaml-plasma>`: A phase defined by a distinct electron temperature or - detailed electron energy distribution function; *New in Cantera 2.6* -- :ref:`pure-fluid <sec-yaml-pure-fluid>`: A phase representing one of several - pure substances including liquid, vapor, two-phase, and supercritical regions -- :ref:`Redlich-Kister <sec-yaml-Redlich-Kister>`: A model that employs the - Redlich-Kister approximation for the excess Gibbs free energy -- :ref:`Redlich-Kwong <sec-yaml-Redlich-Kwong>`: A multi-species mixture obeying - the Redlich-Kwong equation of state. - -Some thermodynamic models use additional fields in the ``phase`` entry, which -are described in the linked documentation. - -Declaring the Elements ----------------------- - -In most cases, it is not necessary to specify the elements present in a phase. -If no ``elements`` field is present, elements will be added automatically using -the definitions of the standard chemical elements based on the composition of -the species present in the phase. - -If non-standard elements such as isotopes need to be represented, or the -ordering of elements within the phase is important, the elements in the phase -may be declared in the optional ``elements`` entry. - -If all of the elements to be added are either standard chemical elements or -defined in the :ref:`elements <sec-yaml-guide-elements>` section of the current -input file, the elements can be specified as a list of element symbols. For -example: - -.. code:: yaml - - phases: - - name: my-mechanism - elements: [H, C, O, Ar] - ... - -To add elements from other top-level sections, from a different file, or from -multiple such sources, a list of single-key mappings can be used -where the key of each mapping specifies the source and the value is a list of -element names. The keys can be: - -- The name of a section within the current file. -- The name of an input file and a section in that file, separated by a slash, - for example ``myfile.yaml/my_elements``. If a relative path is specified, the - directory containing the current file is searched first, followed by the - Cantera data path. -- The name ``default`` to reference the standard chemical elements. - -Example: - -.. code:: yaml - - my-isotopes: - - name: O18 - atomic-weight: 17.9991603 - - phases: - - name: my-phase - elements: - - default: [C, H, Ar] - - my-isotopes: [O18] - - myelements.yaml/uranium: [U235, U238] - species: ... - ... - -The order of the elements specified in the input file determines the order of -the elements in the phase when it is imported by Cantera. - -Declaring the Species ---------------------- - -If the species present in the phase corresponds to those species defined in the -``species`` section of the input file, the ``species`` field may be omitted, and -those species will be added to the phase automatically. As a more explicit -alternative, the ``species`` field may be set to the string ``all``. - -To include specific species from the ``species`` section of the input file, the -``species`` entry can be a list of species names from that section. For example: - -.. code:: yaml - - phases: - - name: my-phase - species: [H2, O2, H2O] - ... - -If species are defined in multiple input file sections, the ``species`` entry -can be a list of single-key mappings, where the key of each mapping specifies -the source and the value is either the string ``all`` or a list of species -names. Each key can be either the name of a section within the current input -file or the name of a different file and a section in that file, separated by a -slash. If a relative path is specified, the directory containing the current -file is searched first, followed by the Cantera data path. Example: - -.. code:: yaml - - phases: - - name: my-phase - species: - - species: [O2, N2] - - more_species: all - - subdir/myfile.yaml/species: [NO2, N2O] - ... - -The order of species specified in the input file determines the order of the -species in the phase when it is imported by Cantera. - -Species containing elements that are not declared within the phase may be -skipped by setting the ``skip-undeclared-elements`` field to ``true``. For -example, to add all species from the ``species`` section that contain only -hydrogen or oxygen, the phase definition could contain: - -.. code:: yaml - - phases: - - name: hydrogen-and-oxygen - elements: [H, O] - species: all - skip-undeclared-elements: true - ... - -Setting the Kinetics Model --------------------------- - -The kinetics model to be used, if any, is specified in the ``kinetics`` field. -Supported model strings are: - -- `gas <{{% ct_docs doxygen/html/de/dae/classCantera_1_1GasKinetics.html#details %}}>`__ -- `surface <{{% ct_docs doxygen/html/d1/d72/classCantera_1_1InterfaceKinetics.html#details %}}>`__ -- `edge <{{% ct_docs doxygen/html/d0/df0/classCantera_1_1EdgeKinetics.html#details %}}>`__ - -If omitted, no kinetics model will be used. - -Declaring the Reactions ------------------------ - -If a kinetics model has been specified, reactions may be added to the phase. By -default, all reactions from the ``reactions`` section of the input file will be -added. Equivalently, the ``reactions`` entry may be specified as the string -``all``. - -To disable automatic addition of reactions from the ``reactions`` section, the -``reactions`` entry may be set to ``none``. This may be useful if reactions will -be added programmatically after the phase is constructed. The ``reactions`` -field must be set to ``none`` if a kinetics model has been specified but there -is no ``reactions`` section in the input file. - -To include only those reactions from the ``reactions`` section where all of the -species involved are declared as being in the phase, the ``reactions`` entry -can be set to the string ``declared-species``. - -To include reactions from multiple sections or other files, the ``reactions`` -entry can be given as a list of section names, for example: - -.. code:: yaml - - phases: - - name: my-phase - ... - reactions: - - OH_submechanism - - otherfile.yaml/C1-reactions - - otherfile.yaml/C2-reactions - ... - -To include reactions from multiple sections or other files while only including -reactions involving declared species, a list of single-key mappings can be used, -where the key is the section name (or file and section name) and the value is -either the string ``all`` or the string ``declared-species``. For example: - -.. code:: yaml - - phases: - - name: my-phase - ... - reactions: - - OH_submechanism: all - - otherfile.yaml/C1-reactions: all - - otherfile.yaml/C2-reactions: declared-species - ... - -To permit reactions containing third-body efficiencies for species not present -in the phase, the additional field ``skip-undeclared-third-bodies`` may be added -to the phase entry with the value ``true``. - -Setting the Transport Model ---------------------------- - -To enable transport property calculation, the transport model to be used can be -specified in the ``transport`` field. Supported models are: - -- `high-pressure <{{% ct_docs doxygen/html/d9/d63/classCantera_1_1HighPressureGasTransport.html#details %}}>`__: - A model for high-pressure gas transport properties based on a method of - corresponding states -- `ionized-gas <{{% ct_docs doxygen/html/d4/d65/classCantera_1_1IonGasTransport.html#details %}}>`__: - A model implementing the Stockmayer-(n,6,4) model for transport of ions in - a gas -- `mixture-averaged <{{% ct_docs doxygen/html/d9/d17/classCantera_1_1MixTransport.html#details %}}>`__: - The mixture-averaged transport model for ideal gases -- `mixture-averaged-CK <{{% ct_docs doxygen/html/d9/d17/classCantera_1_1MixTransport.html#details %}}>`__: - The mixture-averaged transport model for ideal gases, using polynomial - fits corresponding to Chemkin-II -- `multicomponent <{{% ct_docs doxygen/html/df/d7c/classCantera_1_1MultiTransport.html#details %}}>`__: - The multicomponent transport model for ideal gases -- `multicomponent-CK <{{% ct_docs doxygen/html/df/d7c/classCantera_1_1MultiTransport.html#details %}}>`__: - The multicomponent transport model for ideal gases, using polynomial fits - corresponding to Chemkin-II -- `unity-Lewis-number <{{% ct_docs doxygen/html/d3/dd6/classCantera_1_1UnityLewisTransport.html#details %}}>`__: - A transport model for ideal gases, where diffusion coefficients for all - species are set so that the Lewis number is 1 -- `water <{{% ct_docs doxygen/html/df/d1f/classCantera_1_1WaterTransport.html#details %}}>`__: - A transport model for pure water applicable in both liquid and vapor phases - -Declaring Adjacent Phases -------------------------- - -For interface phases (surfaces and edges), the names of phases adjacent to the interface -can be specified, in which case these additional phases can be automatically constructed -when creating the interface phase. This behavior is useful when the interface has -reactions that include species from one of these adjacent phases, since those phases -must be known when adding such reactions to the interface. - -If the definitions of the adjacent phases are contained in the `phases` section of the -same input file as the interface, they can be specified as a list of names: - -.. code:: yaml - - phases: - - name: my-surface-phase - ... - adjacent: [gas, bulk] - ... - - name: gas - ... - - name: bulk - ... - -Alternatively, if the adjacent phase definitions are in other sections or other input -files, they can be specified as a list of single-key mappings where the key is the -section name (or file and section name) and the value is the phase name: - -.. code:: yaml - - phases: - - name: my-surface-phase - ... - adjacent: - - {my-other-phases: gas} - - {path/to/other-file.yaml/phases: bulk} # a phase defined in the 'phases' section - # of a different YAML file - ... - - my-other-phases: - - name: gas - ... - -Since an interface kinetics mechanism is defined for the lowest-dimensional phase -involved in the mechanism, only higher-dimensional adjacent phases should be specified. -For example, when defining a surface, adjacent bulk phases may be specified, but -adjacent edges must not. - -Setting the Initial State -------------------------- - -The state of a phase can be set using two properties to set the thermodynamic -state, plus the composition. This state is specified as a mapping in the -``state`` field of ``phase`` entry. - -The thermodynamic state can be set in terms of two of the following properties, -with the valid property pairs depending on the phase model: - -- ``temperature`` or ``T`` -- ``pressure`` or ``P`` -- ``enthalpy`` or ``H`` -- ``entropy`` or ``S`` -- ``int-energy``, ``internal-energy`` or ``U`` -- ``specific-volume`` or ``V`` -- ``density`` or ``D`` -- ``vapor-fraction`` or ``Q`` - -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`` - -Examples: - -.. code:: yaml - - phases: - - name: my-phase - ... - state: - T: 300 K - P: 101325 Pa - X: {O2: 1.0, N2: 3.76} - - name: my-other-phase - ... - state: - density: 100 kg/m^3 - T: 298 - Y: - CH4: 0.2 - C3H8: 0.1 - CO2: 0.7 - -For pure fluid phases, the temperature, pressure, and vapor fraction may all be -specified if and only if they define a consistent state. - -Examples --------- - -The following input file defines two equivalent gas phases including all -reactions and species defined in the input file. The species and reaction data -is not shown for clarity. In the second case, the phase definition is simplified -by having the elements added based on the species definitions, taking the -species definitions from the default ``species`` section, and reactions from the -default ``reactions`` section. - -.. code:: yaml - - phases: - - name: gas1 - thermo: ideal-gas - elements: [O, H, N, Ar] - species: [H2, H, O, O2, OH, H2O, HO2, H2O2, N2, AR] - kinetics: gas - reactions: all - transport: mixture-averaged - state: - T: 300.0 - P: 1.01325e+05 - - name: gas2 - thermo: ideal-gas - kinetics: gas - transport: mixture-averaged - state: {T: 300.0, 1 atm} - - species: - - H2: ... - - H: ... - ... - - AR: ... - - reactions: - ... - -An input file defining an interface and its adjacent bulk phases, with full -species data not shown for clarity: - -.. code:: yaml - - phases: - - name: graphite - thermo: lattice - species: - - graphite-species: all - state: {T: 300, P: 101325, X: {C6: 1.0, LiC6: 1e-5}} - density: 2.26 g/cm^3 - - - name: electrolyte - thermo: lattice - species: [{electrolyte-species: all}] - density: 1208.2 kg/m^3 - state: - T: 300 - P: 101325 - X: {Li+(e): 0.08, PF6-(e): 0.08, EC(e): 0.28, EMC(e): 0.56} - - - name: anode-surface - thermo: ideal-surface - adjacent: [graphite, electrolyte] - kinetics: surface - reactions: [graphite-anode-reactions] - species: [{anode-species: all}] - site-density: 1.0 mol/cm^2 - state: {T: 300, P: 101325} - - graphite-species: - - name: C6 - ... - - name: LiC6 - ... - - electrolyte-species: - - name: Li+(e) - ... - - name: PF6-(e) - ... - - name: EC(e) - ... - - name: EMC(e) - ... - - anode-species: - - name: (int) - ... - - graphite-anode-reactions: - - equation: LiC6 <=> Li+(e) + C6 - rate-constant: [5.74, 0.0, 0.0] - beta: 0.4 - - -.. container:: container - - .. container:: row - - .. container:: col-4 text-center offset-4 - - .. container:: btn btn-primary - :tagname: a - :attributes: href=defining-phases.html - - Return: Defining Phases - - .. container:: col-4 text-right - - .. container:: btn btn-primary - :tagname: a - :attributes: href=yaml-species.html - - Next: Elements and Species diff --git a/pages/tutorials/yaml/reactions.rst b/pages/tutorials/yaml/reactions.rst deleted file mode 100644 index 791d1c589..000000000 --- a/pages/tutorials/yaml/reactions.rst +++ /dev/null @@ -1,261 +0,0 @@ -.. slug: reactions -.. title: Reactions -.. has_math: true - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Reactions</h1> - - .. class:: lead - - A description of how reactions are defined in YAML input files. For additional - information, see: :ref:`YAML reaction <sec-yaml-reactions>` documentation. - -Common Attributes -================= - -Cantera supports a number of different types of reactions, including several -types of homogeneous reactions, surface reactions, and electrochemical -reactions. The reaction entries for all reaction types some common features. -These general fields of a reaction entry are described first, followed by fields -used for specific reaction types. - -The Reaction Equation ---------------------- - -The reaction equation, specified in the ``equation`` field of the reaction -entry, determines the reactant and product stoichiometry. All tokens (species -names, stoichiometric coefficients, ``+``, and ``<=>``) in the reaction equation -must be separated with spaces. Some examples of correctly and incorrectly -formatted reaction equations are shown below: - -.. code:: yaml - - - equation: 2 CH2 <=> CH + CH3 # OK - - equation: 2 CH2<=>CH + CH3 # error - spaces required around '<=>'' - - equation: 2CH2 <=> CH + CH3 # error - space required between '2' and 'CH2' - - equation: CH2 + CH2 <=> CH + CH3 # OK - - equation: 2 CH2 <=> CH+CH3 # error - spaces required around '+' - -Whether the reaction is reversible or not is determined by the form of the -equality sign in the reaction equation. If either ``<=>`` or ``=`` is found, -then the reaction is regarded as reversible, and the reverse rate will be -computed based on the equilibrium constant. If, on the other hand, ``=>`` is -found, the reaction will be treated as irreversible. - -Reaction type -------------- - -The type of the rate coefficient parameterization may be specified in the -``type`` field of the ``reaction`` entry. Available reaction types are: - -- :ref:`elementary <sec-yaml-elementary>`: A reaction with a rate constant - parameterized by a modified Arrhenius expression -- :ref:`three-body <sec-yaml-three-body>`: A reaction involving a third-body - collision. *Changed in Cantera 3.0: three body reactions are detected based on the - reaction equation; the rate parameterization is independent. For three body reactions - with Arrhenius rate parameterizations, specifying the "type" is optional.* -- :ref:`falloff <sec-yaml-falloff>`: A pressure-dependent reaction where the - rate depends on the third-body concentration at low pressure but not at high - pressure -- :ref:`chemically-activated <sec-yaml-chemically-activated>`: A - pressure-dependent reaction where the rate depends on the third-body - concentration at high pressure but not at low pressure -- :ref:`pressure-dependent-Arrhenius <sec-yaml-pressure-dependent-Arrhenius>`: A - reaction rate parameterized by logarithmically interpolating between modified - Arrhenius expressions at different pressures -- :ref:`Chebyshev <sec-yaml-Chebyshev>`: A reaction rate parameterized by a - bivariate Chebyshev polynomial in pressure and temperature -- :ref:`Blowers-Masel <sec-yaml-blowers-masel>`: A - reaction rate constant parameterized as a modified Arrhenius reaction with - one additional bond energy parameter to scale the activation energy according - to the enthalpy of the reaction *(New in Cantera 2.6)* - -Additional parameters defining the rate constant for each of these reaction -types are described in the documentation linked above. - -The default parameterization is ``elementary``. Reactions involving surface -species are automatically identified as :ref:`interface <sec-yaml-interface-Arrhenius>` -reactions, reactions involving surface species with specified ``type`` as ``Blowers-Masel`` -are treated as :ref:`interface-Blowers-Masel <sec-yaml-interface-Blowers-Masel>`, -and reactions involving charge transfer are automatically identified as -:ref:`electrochemical <sec-yaml-electrochemical-reaction>` reactions. - -Arrhenius Expressions ---------------------- - -Most reaction types in Cantera are parameterized by one or more modified -Arrhenius expressions, such as - -.. math:: - - A T^b e^{-E_a / RT} - -where :math:`A` is the pre-exponential factor, :math:`T` is the temperature, -:math:`b` is the temperature exponent, :math:`E_a` is the activation energy, -and :math:`R` is the gas constant. Rates in this form can be written as YAML -mappings. For example: - -.. code:: yaml - - {A: 1.0e13, b: 0, E: 7.3 kcal/mol} - -The units of :math:`A` can be specified explicitly if desired. If not specified, -they will be determined based on the ``quantity``, ``length``, and ``time`` -units specified in the governing ``units`` fields. Since the units of :math:`A` -depend on the reaction order, the units of each reactant concentration -(dependent on phase type and dimensionality), and the units of the rate of -progress (different for homogeneous and heterogeneous reactions), it is usually -best not to specify units for :math:`A`, in which case they will be computed -taking all of these factors into account. - -Note: if :math:`b \ne 0`, then the term :math:`T^b` should have units of -:math:`\mathrm{K}^b`, which would change the units of :math:`A`. This is not done, -however, so the units associated with :math:`A` are really the units for -:math:`k_f`. One way to formally express this is to replace :math:`T^b` by the -non-dimensional quantity :math:`[T/(1\;\mathrm{K})]^b`. - -The key ``E`` is used to specify :math:`E_a`. - -.. _sec-yaml-reaction-options: - -Duplicate Reactions -------------------- - -When a reaction is imported into a phase, it is checked to see that it is not a -duplicate of another reaction already present in the phase, and normally an -error results if a duplicate is found. But in some cases, it may be appropriate -to include duplicate reactions, for example if a reaction can proceed through -two distinctly different pathways, each with its own rate expression. Another -case where duplicate reactions can be used is if it is desired to implement a -reaction rate coefficient of the form: - -.. math:: - - 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 :math:`N` duplicate reactions, and assigning one rate -coefficient in the sum to each reaction. By adding the field: - -.. code:: yaml - - 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. - -Negative Pre-exponential Factors --------------------------------- - -If some of the terms in the above sum have negative :math:`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 :math:`A` parameters are acceptable can be indicated by -adding the field: - -.. code:: yaml - - negative-A: true - -Reaction Orders ---------------- - -Explicit reaction orders different from the stoichiometric coefficients are -sometimes used for non-elementary reactions. For example, consider the global -reaction: - -.. math:: - - \mathrm{C_8H_{18} + 12.5 O_2 \rightarrow 8 CO_2 + 9 H_2O} - -the forward rate constant might be given as [#Westbrook1981]_: - -.. math:: - - k_f = 4.6 \times 10^{11} [\mathrm{C_8H_{18}}]^{0.25} [\mathrm{O_2}]^{1.5} - \exp\left(\frac{30.0\,\mathrm{kcal/mol}}{RT}\right) - -This reaction could be defined as: - -.. code:: yaml - - - equation: C8H18 + 12.5 O2 => 8 CO2 + 9 H2O - rate-constant: {A: 4.6e11, b: 0.0, Ea: 30.0 kcal/mol} - orders: {C8H18: 0.25, O2: 1.5} - -Special care is required in this case since the units of the pre-exponential -factor depend on the sum of the reaction orders, which may not be an integer. - -Note that you can change reaction orders only for irreversible reactions. - -Negative Reaction Orders -~~~~~~~~~~~~~~~~~~~~~~~~ - -Normally, reaction orders are required to be positive. However, in some cases -negative reaction orders provide better fits for experimental data. In these -cases, the default behavior may be overridden by adding the ``negative-orders`` -field to the reaction entry. For example: - -.. code:: yaml - - - equation: C8H18 + 12.5 O2 => 8 CO2 + 9 H2O - rate-constant: {A: 4.6e11, b: 0.0, Ea: 30.0 kcal/mol} - orders: {C8H18: -0.25, O2: 1.75} - negative-orders: true - -Non-reactant Orders -~~~~~~~~~~~~~~~~~~~ - -Some global reactions could have reactions orders for non-reactant species. In -this case, the ``nonreactant-orders`` field must be added to the reaction entry: - -.. code:: yaml - - - equation: C8H18 + 12.5 O2 => 8 CO2 + 9 H2O - rate-constant: {A: 4.6e11, b: 0.0, Ea: 30.0 kcal/mol} - orders: {C8H18: -0.25, CO: 0.15} - negative-orders: true - nonreactant-orders: true - - -.. container:: container - - .. container:: row - - .. container:: col-4 text-left - - .. container:: btn btn-primary - :tagname: a - :attributes: href=yaml-species.html - title="Elements and Species" - - Previous: Elements and Species - - .. container:: col-4 text-center - - .. container:: btn btn-primary - :tagname: a - :attributes: href=defining-phases.html - title="Defining Phases" - - Return: Defining Phases - - .. container:: col-4 text-right - - .. container:: btn btn-primary - :tagname: a - :attributes: href=yaml-format.html - title="YAML Format Tutorial" - - Next: YAML Format Tutorial - -.. rubric:: References - -.. [#Westbrook1981] C. K. Westbrook and F. L. Dryer. Simplified reaction - mechanisms for the oxidation of hydrocarbon fuels in flames. *Combustion - Science and Technology* **27**, pp. 31--43. 1981. diff --git a/pages/tutorials/yaml/species.rst b/pages/tutorials/yaml/species.rst deleted file mode 100644 index acc3c6e4d..000000000 --- a/pages/tutorials/yaml/species.rst +++ /dev/null @@ -1,226 +0,0 @@ -.. slug: yaml-species -.. title: Elements and Species -.. has_math: true - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">Elements and Species in YAML</h1> - - .. class:: lead - - A description of how elements and species are defined in YAML input files. - For additional information, see: :ref:`YAML elements <sec-yaml-elements>` - and :ref:`YAML species <sec-yaml-species>` documentation. - -.. _sec-yaml-guide-elements: - -Elements -======== - -Cantera provides built-in definitions for the chemical elements, including -values for their atomic weights taken from IUPAC / CIAAW. These elements can be -used by specifying the corresponding atomic symbols when specifying the -composition of species. - -In order to give a name to a particular isotope or a virtual element -representing a surface site, a custom ``element`` entry can be used. The default -location for ``element`` entries is the ``elements`` section of the input file. -Elements defined in this section will automatically be considered for addition -to phases defined in the same file. Elements can be defined in other sections of -the input file if those sections are named explicitly in the ``elements`` field -of the phase definition. - -An element entry has the following fields: - -- ``symbol``: The symbol to be used for the element, for example when specifying - the composition of a 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: - -.. code:: yaml - - elements: - - symbol: C13 - atomic-weight: 13.003354826 - atomic-number: 12 - - symbol: O-18 - atomic-weight: 17.9991603 - -.. _sec-yaml-guide-species: - -Species -======= - -A species entry in Cantera is used to specify the name, composition, -thermodynamic, and transport properties of an individual species. - -The default location for species entries is in the ``species`` section of the -input file. Species defined in this section will automatically be considered for -addition to phases defined in the same file. Species can be defined in other -sections of the input file or in other input files, and these species -definitions can be used in phase definitions by explicitly referencing the -section name. - -Species Name ------------- - -The name of a species is given in the ``name`` field of a ``species`` entry. Names -may include almost all printable characters, with the exception of spaces. The -use of some characters such as ``[``, ``]``, and ``,`` may require that species -names be enclosed in quotes when written in YAML. Some valid species names given -in a YAML list include: - -.. code:: yaml - - [CH4, methane, argon_2+, "C[CH2]", CH2(singlet), "H2O,l"] - -Elemental Composition ---------------------- - -The elemental composition of a species is specified as a mapping in the -``composition`` entry. - -For gaseous species, the elemental composition is well-defined, since the -species represent distinct molecules. For species in solid or liquid solutions, -or on surfaces, there may be several possible ways of defining the species. For -example, an aqueous species might be defined with or without including the water -molecules in the solvation cage surrounding it. - -For surface species, it is possible for the ``composition`` mapping to be empty, -in which case the species is composed of nothing, and represents an empty -surface site. This can also be done to represent vacancies in solids. A charged -vacancy can be defined to be composed solely of electrons. - -The number of atoms of an element must be non-negative, except for the special -"element" ``E`` that represents an electron. - -Examples: - -.. code:: 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 - -Thermodynamic Properties ------------------------- - -In addition to the thermodynamic model used at the phase level for computing -properties, parameterizations are usually required for the enthalpy, entropy, -and specific heat capacities of individual species under standard conditions. -These parameterizations are provided in the ``thermo`` field of each ``species`` -entry. - -The parameterization used to provide this information is specified by the -``model`` field of the ``thermo`` field. The models available are: - -- :ref:`NASA7 <sec-yaml-nasa7>`: 7-coefficient NASA polynomials in one or two - temperature regions -- :ref:`NASA9 <sec-yaml-nasa9>`: 9-coefficient NASA polynomials in one or more - temperature regions -- :ref:`Shomate <sec-yaml-shomate>`: Shomate polynomials in one or two - temperature regions -- :ref:`constant-cp <sec-yaml-constcp>`: Constant heat capacity -- :ref:`piecewise-Gibbs <sec-yaml-piecewise-gibbs>`: Interpolation between - tabulated Gibbs free energies using a constant heat capacity in each - temperature interval - -The fields used by each model are described and examples provided in the linked -documentation. - -Species Equation of State -------------------------- - -For some phase thermodynamic models, additional equation of state -parameterizations are needed for each species. This information is provided in -the ``equation-of-state`` field of each ``species`` entry, with the type of -parameterization used specified by the ``model`` field of the -``equation-of-state`` field. The models available are: - -- :ref:`constant-volume <sec-yaml-eos-constant-volume>`: A fixed value of mass - density, molar density, or molar volume -- :ref:`density-temperature-polynomial <sec-yaml-eos-density-temperature-polynomial>`: - Mass density parameterized using a cubic polynomial in temperature -- :ref:`HKFT <sec-yaml-eos-hkft>`: The Helgeson-Kirkham-Flowers-Tanger model for - aqueous species -- :ref:`ideal-gas <sec-yaml-eos-ideal-gas>`: A species following the ideal gas - law. *Deprecated in Cantera 3.0; handled at the phase level for all species in an - ideal gas.* -- :ref:`ions-from-neutral-molecule <sec-yaml-eos-ions-from-neutral>`: Used with - the ``ions-from-neutral-molecule`` phase model; *Deprecated in Cantera 3.0* -- :ref:`liquid-water-IAPWS95 <sec-yaml-eos-liquid-water-iapws95>`: The IAPWS95 - equation of state for water, applied only in the liquid region -- :ref:`molar-volume-temperature-polynomial <sec-yaml-eos-molar-volume-temperature-polynomial>`: - Molar volume parameterized using a cubic polynomial in temperature -- :ref:`Peng-Robinson <sec-yaml-eos-peng-robinson>`: A species following the - Peng-Robinson real gas model; *New in Cantera 3.0* -- :ref:`Redlich-Kwong <sec-yaml-eos-redlich-kwong>`: - A species which follows the Redlich-Kwong equation of state - -The fields used by each model are described and examples provided in the linked -documentation. - -.. _sec-yaml-guide-species-transport: - -Species Transport Coefficients ------------------------------- - -Transport-related parameters for each species are needed in order to calculate -transport properties of a phase. These parameters are provided in the -``transport`` field of each ``species`` entry, with the type of the -parameterization used specified by the ``model`` field of the ``transport`` -field. The only model type specifically handled is ``gas``. The parameters used -depend on the transport model specified at the phase level. The full set of -possible parameters is described in the :ref:`API documentation -<sec-yaml-species-transport>`. - -An example of a ``transport`` entry: - -.. code:: yaml - - transport: - model: gas - geometry: linear - well-depth: 107.4 - diameter: 3.458 - polarizability: 1.6 - rotational-relaxation: 3.8 - - -.. container:: container - - .. container:: row - - .. container:: col-4 text-left - - .. container:: btn btn-primary - :tagname: a - :attributes: href=phases.html - title="Phases and Interfaces" - - Previous: Phases and Interfaces - - .. container:: col-4 text-center - - .. container:: btn btn-primary - :tagname: a - :attributes: href=defining-phases.html - title="Defining Phases" - - Return: Defining Phases - - .. container:: col-4 text-right - - .. container:: btn btn-primary - :tagname: a - :attributes: href=reactions.html - title=Reactions - - Next: Reactions diff --git a/pages/tutorials/yaml/yaml-format.rst b/pages/tutorials/yaml/yaml-format.rst deleted file mode 100644 index c00f923e0..000000000 --- a/pages/tutorials/yaml/yaml-format.rst +++ /dev/null @@ -1,366 +0,0 @@ -.. slug: yaml-format -.. title: YAML Format Tutorial - -.. jumbotron:: - - .. raw:: html - - <h1 class="display-4">YAML Format Tutorial</h1> - - .. class:: lead - - Here we describe the syntax and structure of Cantera YAML files, how - dimensional values in Cantera YAML files are handled, and how to - understand some of the error messages that may be encountered when reading - these input files. - -Syntax -====== - -Cantera YAML files use a subset of the `YAML 1.2 -<https://yaml.org/spec/1.2/spec.html>`__ specification. Cantera YAML files -consist of individual values, which may be strings, numbers or booleans, that -are then composed as elements of nested mappings and sequences. - -Strings -------- - -Strings may be generally written without quotes, but may be enclosed in single -quotes or double quotes if needed in order to avoid certain parsing ambiguities. - -.. code:: yaml - - A string - Another 'string' - "A string: that requires quotes" - -Numbers -------- - -Numbers can be written as integers, decimal values, or using E-notation - -.. code:: yaml - - 3 - 3.14 - 6.022e23 - -Booleans --------- - -Boolean values in YAML are written as the words ``true`` or ``false``. - -Sequences ---------- - -A sequence of multiple items is specified by separating the items by commas and -enclosing them in square brackets. The individual items can have any type -- -strings, integers, floating-point numbers, mappings, or sequences. - -.. code:: yaml - - elements: [O, H, C, N, Ar] - temperature-ranges: [200.0, 1000.0, 3500.0] - -The syntax above, using square brackets to define a list, is called **flow style** -in YAML. Sequences can also be written in **block style**, using one line -for each item in the sequence, with each line starting with a dash: - -.. code:: yaml - - elements: - - O - - H - - C - - N - - Ar - -Sequences can also be nested. The following examples are all equivalent: - -.. code:: yaml - - data: [[1, 2], [3, 4]] - - data: - - - - 1 - - 2 - - - - 3 - - 4 - - data: - - - 1 - - 2 - - - 3 - - 4 - -Mappings --------- - -A mapping is a container consisting of key--value pairs. The keys in a mapping -must be unique. Like sequences, there are two ways to write a mapping. In the -**flow style**, the mapping is enclosed in curly brackets, colons (followed by -spaces) are used to separate keys and values, and key--value pairs are separated -by commas: - -.. code:: yaml - - composition: {H: 2, C: 1, O: 1} - -In the **block style**, each key is written on a new line, followed by a colon. -The value can be placed either on the same line, or on the following line, -indented one level: - -.. code:: yaml - - composition: - H: 2 - C: - 1 - O: 1 - -All keys in Cantera YAML files are treated as strings. A Cantera YAML file is -itself a mapping, usually in the **block style**. We refer to the keys in this -top-level mapping as the **sections** of the input file. - -Sequences of Mappings ---------------------- - -A common structure in Cantera input files is a nested sequence of mappings. This -can be written in the **block style** as: - -.. code:: yaml - - - equation: O2 + CO <=> O + CO2 - rate-constant: {A: 2.5e+12, b: 0, Ea: 47800} - - equation: O2 + CH2O <=> HO2 + HCO - rate-constant: {A: 1.0e+14, b: 0, Ea: 40000} - - equation: H + O2 + M <=> HO2 + M - type: three-body - rate-constant: {A: 2.8e+18, b: -0.86, Ea: 0} - efficiencies: {AR: 0, C2H6: 1.5, CO: 0.75, CO2: 1.5, H2O: 0, N2: 0, O2: 0} - -The keys in each mapping need not be the same. In this example, each of the -three mappings in the sequence has ``equation`` and ``rate-constant`` keys, -while only the third entry has ``type`` and ``efficiencies`` keys. - -Comments --------- - -The character ``#`` is the comment character. Everything to the right of this -character on a line is ignored: - -.. code:: yaml - - # set the default units - units: - length: cm # use centimeters for length - quantity: mol # use moles for quantity - -Dimensional Values -================== - -Many fields have numerical values that represent dimensional quantities---a -pressure, or a density, for example. If these are entered without specifying the -units, the default units (set by the ``units`` directive) will be used. However, -it is also possible to specify the units for each individual dimensional -quantity, unless stated otherwise. All that is required is to write the units -after the value, separated by a space: - -.. code:: yaml - - pressure: 1.0e5 # default is Pascals - pressure: 1.0 bar # this is equivalent - density: 4.0 g/cm^3 - density: 4000.0 # kg/m^3 - -Compound unit strings may be used, as long as a few rules are followed: - -1. Units in the denominator follow ``/``. -2. Units in the numerator follow ``*``, except for the first one. -3. Numerical exponents follow the unit string with a ``^`` character. - -Examples of compound units: - -.. code:: yaml - - A: 1.0e20 cm^6/mol^2/s # OK - h: 6.626e-34 J*s # OK - density: 3.0 g*cm^-3 # OK - A: 1.0e20 cm6/mol/s # error (missing '^') - A: 1.0e20 cm^6/mol^2-s # error ('s' should be in denominator) - density: 3.0g/cm^3 # error (missing space between value and units) - -See the `Units API <{{% ct_docs sphinx/html/yaml/general.html#units %}}>`__ -documentation for additional details, including the full set of supported units. - -Default units -------------- - -Default units that apply to a whole input file or some portion thereof can be -set using ``units`` mapping. A ``units`` mapping placed at the top level of an -input file applies to the entire file. A ``units`` mapping placed as a member of -another mapping applies to that mapping and any nested mappings or sequences, and overrides higher-level ``units`` mappings: - -.. code:: yaml - - units: {length: cm, mass: kg} - section1: - units: {length: m} - density: 4000 # interpreted as 4000 kg/m^3 - section2: - density: 0.1 # interpreted as 0.1 kg/cm^3 - section3: - - units: {mass: mg} # must be the first item in the list - - name: species1 - density: 5e4 # interpreted as 5e4 mg/cm^3 - -Default units may be set for ``mass``, ``length``, ``time``, ``quantity``, -``pressure``, ``energy``, and ``activation-energy``. - -Error Handling -============== - -During processing of an input file, errors may be encountered. These could be -syntax errors, or could be ones that are flagged as errors by Cantera due to -some apparent inconsistency in the data---an unphysical value, a species that -contains an undeclared element, a reaction that contains an undeclared species, -missing species or element definitions, multiple definitions of elements, -species, or reactions, and so on. - -Syntax Errors -------------- - -Syntax errors are caught by the YAML parser, and must be corrected before -proceeding further. If a syntax error is encountered, Cantera will raise an -exception which includes the location of the error. Additional information such -as a traceback showing where in the code the input file was being read may be -printed as well. - -For example, consider the following input file, which is intended to create a -gas with the species and reactions of GRI-Mech 3.0, but is missing the colon -which is needed after the ``thermo`` key: - -.. code:: yaml - - phases: - - name: gas - thermo ideal-gas - kinetics: gas - elements: [H, O] - species: [{gri30.yaml/species: all}] - reactions: [gri30.yaml/reactions] - -When this definition is imported into an application, an error message like the -following would be printed to the screen, and execution of the program or script -would terminate: - -.. code:: python - - Traceback (most recent call last): - File "<stdin>", line 1, in <module> - File "/some/path/cantera/base.pyx", line 25, in cantera._cantera._SolutionBase.__cinit__ - self._init_yaml(infile, phaseid, phases, yaml) - File "/some/path/cantera/base.pyx", line 49, in cantera._cantera._SolutionBase._init_yaml - root = AnyMapFromYamlFile(stringify(infile)) - cantera._cantera.CanteraError: - *********************************************************************** - InputFileError thrown by AnyMap::fromYamlFile: - Error on line 4 of ./gas.yaml: - illegal map value - | Line | - | 1 | phases: - | 2 | - name: gas - | 3 | thermo ideal-gas - > 4 > kinetics: gas - ^ - | 5 | elements: [H, O] - | 6 | species: [{gri30.yaml/species: all}] - | 7 | reactions: [gri30.yaml/reactions] - *********************************************************************** - -The top part of the error message shows the chain of functions that were called -before the error was encountered. For the most part, these are internal Cantera -functions not of direct concern here. The relevant part of this error message is -the part between the lines of asterisks. This message says that the YAML parser -ran into a problem on line 4 of ``gas.yaml``. In many cases, including this one, -the parser will fail somewhere *after* the actual problem with the input file, -since it must continue parsing until it finds something that cannot possibly be -valid YAML syntax. In this case, the problem from the parser's perspective is -that the key which started on line 3 continues across a new line before it finds -a colon that can be considered as the separator. Since a key can't be broken -across lines like this, the parser indicates the error at the point where it -found the colon. By looking back from the indicated point of the error, we can -see that the problem is the missing colon in the previous line. - -Cantera Errors --------------- - -Now let's consider the other class of errors, ones that Cantera itself -detects. Continuing the example above, suppose that the missing colon is -corrected, and the input file processed again. Again an error message results, -but this time it is from Cantera: - -.. code:: python - - Traceback (most recent call last): - File "<stdin>", line 1, in <module> - File "/some/path/cantera/base.pyx", line 25, in cantera._cantera._SolutionBase.__cinit__ - self._init_yaml(infile, phaseid, phases, yaml) - File "/some/path/cantera/base.pyx", line 49, in cantera._cantera._SolutionBase._init_yaml - root = AnyMapFromYamlFile(stringify(infile)) - cantera._cantera.CanteraError: - *********************************************************************** - CanteraError thrown by Phase::addSpecies: - Species 'C' contains an undefined element 'C'. - *********************************************************************** - -The problem is that the phase definition specifies that all species are to be -imported from the ``gri30`` mechanism, but only the elements H and O are -declared. The ``gri30`` mechanism contains species composed of the elements H, -O, C, N, and Ar. If the definition is modified to declare these additional -elements: - -.. code:: yaml - - phases: - - name: gas - thermo: ideal-gas - kinetics: gas - elements: [H, O, C, N, Ar] - species: [{gri30.yaml/species: all}] - reactions: [gri30.yaml/reactions] - -it may be imported successfully. - -.. container:: container - - .. container:: row - - .. container:: col-4 text-left - - .. container:: btn btn-primary - :tagname: a - :attributes: href=reactions.html - title="Reactions" - - Previous: Reactions - - .. container:: col-4 text-center - - .. container:: btn btn-primary - :tagname: a - :attributes: href=defining-phases.html - title="Defining Phases" - - Return: Defining Phases - - .. container:: col-4 text-right - - .. container:: btn btn-primary - :tagname: a - :attributes: href={{% ct_docs sphinx/html/yaml/index.html %}} - title="YAML Format Reference" - - Next: YAML Format Reference diff --git a/pdm.toml b/pdm.toml new file mode 100644 index 000000000..0ef489f39 --- /dev/null +++ b/pdm.toml @@ -0,0 +1,7 @@ +[python] +use_venv = true + +[venv] +backend = "venv" +in_project = true +with_pip = true diff --git a/plugins/__init__.py b/plugins/__init__.py deleted file mode 100644 index fd7e25d79..000000000 --- a/plugins/__init__.py +++ /dev/null @@ -1 +0,0 @@ -# Plugin modules go here. \ No newline at end of file diff --git a/plugins/bootstrap.py b/plugins/bootstrap.py deleted file mode 100644 index 2428fb142..000000000 --- a/plugins/bootstrap.py +++ /dev/null @@ -1,294 +0,0 @@ -"""Plugin to format Bootstrap directives. - -Portions of this code are adapted from the bootstrap-rst project -https://github.com/rougier/bootstrap-rst -which is licensed under the MIT license - -Copyright (c) 2014 Nicolas P. Rougier - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN -THE SOFTWARE. -""" - -from docutils import nodes, utils -import docutils -from docutils.parsers.rst import directives, Directive -from nikola.plugin_categories import RestExtension - - -class Bootstrap(RestExtension): - """Extend the reST parser with directives for Bootstrap classes.""" - - name = "boostrap_rst" - - def set_site(self, site): - """Set the Nikola site.""" - self.site = site - directives.register_directive("container", Container) - directives.register_directive("jumbotron", Jumbotron) - directives.register_directive("row", Row) - directives.register_directive("section", Section) - directives.register_directive("card", Card) - directives.register_directive("card-deck", CardDeck) - directives.register_directive("card-body", CardBody) - directives.register_directive("card-header", CardHead) - directives.register_directive("card-footer", CardFoot) - directives.register_directive("button", Button) - directives.register_directive("accordion", Accordion) - - add_node("container", visit_container, depart_container) - - return super(Bootstrap, self).set_site(site) - - -def visit_container(self, node): - """Docutils visit function for the Container.""" - attrs = node.non_default_attributes().copy() - if "classes" in attrs: - del attrs["classes"] - if "endless" in attrs: - del attrs["endless"] - self.body.append(self.starttag(node, node.tagname, **attrs)) - - -def depart_container(self, node): - """Docutils depart function for the Container.""" - if "endless" not in node: - self.body.append("</%s>\n" % node.tagname) - else: - pass - - -class Container(Directive): - """Overridden Container. - - You can choose any tag name just like a barebones computer or a wild card. - Default tag name is div. - This is based on the code at docutils.parsers.rst.directives.html. - Derived classes: - default_class = None - default_tagname = None - default_attributes = None - Derived class example:: - - class Thumbnail(Container): - default_class = ['thumbnail'] - - class Html5Header(Container): - default_tagname = 'header' - - RestructuredText example:: - - .. container:: - :tagname: header - .. container:: navbar navbar-expand-md navbar-dark fixed-top bg-dark - :tagname: nav - .. container:: navbar-brand - :tagname: a - :attributes: href=# - Carousel - .. container:: navbar-toggler - :tagname: button - :attributes: type=button - data-toggle=collapse - data-target=#navbarCollapse - aria-controls=navbarCollapse - aria-expanded=false - aria-label="Toggle navigation" - .. raw:: html - <span class="navbar-toggler-icon"></span> - """ - - optional_arguments = 1 - final_argument_whitespace = True - option_spec = { - "name": directives.unchanged, - "tagname": directives.unchanged, - "attributes": directives.unchanged, - "endless": directives.flag, - } - has_content = True - default_class = None - default_tagname = None - default_attributes = None - default_endless = False - - def set_classes(self, node): - """Set the classes on the node.""" - try: - if self.default_class is not None and self.arguments: - classes = self.default_class + self.arguments - elif self.arguments: - classes = directives.class_option(self.arguments[0]) - else: - classes = self.default_class - except ValueError: - raise self.error( - "Invalid class attribute value for '{}' directive: '{}'.".format( - self.name, self.arguments[0] - ) - ) - - if classes: - node["classes"].extend(classes) - - return node - - def set_tagname(self, node): - """Set the node tagname.""" - try: - if "tagname" in self.options: - node.tagname = self.options.get("tagname", "div") - elif self.default_tagname is not None: - node.tagname = self.default_tagname - else: - node.tagname = "div" - except ValueError: - raise self.error( - "Invalid tag name for '{}' directive: '{}'.".format( - self.name, node.tagname - ) - ) - - return node - - def set_attributes(self, node): - """Set the node attributes.""" - attrs = None - if "attributes" in self.options: - attrs = self.options.get("attributes", "") - elif self.default_attributes: - attrs = self.default_attributes - if attrs is not None: - tokens = attrs.split("\n") - try: - attname, val = utils.extract_name_value(tokens[0])[0] - if attname == "id": - node["ids"].append(val) - else: - node.attributes.update({attname: val}) - except utils.NameValueError: - node["name"] = tokens[0] - for token in tokens[1:]: - try: - attname, val = utils.extract_name_value(token)[0] - if attname == "id": - node["ids"].append(val) - else: - node.attributes.update({attname: val}) - except utils.NameValueError as detail: - line = self.state_machine.line - msg = self.state_machine.reporter.error( - 'Error parsing %s tag attribute "%s": %s.' - % (node.tagname, token, detail), - nodes.literal_block(line, line), - ) - return [msg] - - return node - - def run(self): - """Run the directive.""" - text = "\n".join(self.content) - node = nodes.container(text) - - node = self.set_classes(node) - node = self.set_tagname(node) - node = self.set_attributes(node) - if "endless" in self.options or self.default_endless: - node["endless"] = True - if self.content: - self.state.nested_parse(self.content, self.content_offset, node) - return [node] - - -class Jumbotron(Container): - """Class for Bootstrap ``jumbotron``s.""" - - default_class = ["jumbotron"] - - -class Accordion(Container): - """Class for Bootstrap ``accordion``s.""" - - default_class = ["accordion"] - - -class Row(Container): - """Class for Bootstrap ``row``s.""" - - default_class = ["row"] - - -class Card(Container): - """Class for Bootstrap ``card``s.""" - - default_class = ["card"] - - -class CardDeck(Container): - """Class for Bootstrap ``card-deck``s.""" - - default_class = ["card-deck"] - - -class CardBody(Container): - """Class for Bootstrap ``card-body``s.""" - - default_class = ["card-body"] - - -class CardHead(Container): - """Class for Bootstrap ``card-header``s.""" - - default_class = ["card-header"] - - -class CardFoot(Container): - """Class for Bootstrap ``card-footer``s.""" - - default_class = ["card-footer"] - - -class Section(Container): - """Class for Bootstrap ``section``s.""" - - default_tagname = "section" - - -class Button(Container): - """Class for Bootstrap ``button``s.""" - - default_tagname = "button" - - -def add_node(node_name, visit_function=None, depart_function=None): - """Register a Docutils node class.""" - nodes._add_node_class_names([node_name]) - if visit_function is not None: - setattr( - docutils.writers._html_base.HTMLTranslator, - "visit_" + node_name, - visit_function, - ) - if depart_function is not None: - setattr( - docutils.writers._html_base.HTMLTranslator, - "depart_" + node_name, - depart_function, - ) diff --git a/plugins/bootstrap_rst.plugin b/plugins/bootstrap_rst.plugin deleted file mode 100644 index 20f07f2ef..000000000 --- a/plugins/bootstrap_rst.plugin +++ /dev/null @@ -1,8 +0,0 @@ -[Core] -Name = bootstrap_rst -Module = bootstrap - -[Documentation] -Author = Bryan Weber -Version = 0.1 -Description = Add directives and roles for bootstrap diff --git a/plugins/class.plugin b/plugins/class.plugin deleted file mode 100644 index 35c5c061b..000000000 --- a/plugins/class.plugin +++ /dev/null @@ -1,12 +0,0 @@ -[Core] -name = rest_class -module = rest_class - -[Nikola] -compiler = rest -PluginCategory = CompilerExtension - -[Documentation] -author = Bryan Weber -version = 0.1 -description = Role to link to a class or function in the documentation from other reST files diff --git a/plugins/copy_tree.plugin b/plugins/copy_tree.plugin deleted file mode 100644 index a2f456bde..000000000 --- a/plugins/copy_tree.plugin +++ /dev/null @@ -1,8 +0,0 @@ -[Core] -Name = copy_tree -Module = copy_tree - -[Documentation] -Author = Bryan Weber -Version = 0.1 -Description = Copy a tree rather than a file diff --git a/plugins/copy_tree.py b/plugins/copy_tree.py deleted file mode 100644 index c9cbdeae6..000000000 --- a/plugins/copy_tree.py +++ /dev/null @@ -1,61 +0,0 @@ -"""Copy an entire tree of files. - -Replacement plugin for the default Nikola copy_tree plugin. -This plugin copies entire folders at once, rather than individually -copying files within the folder. This substantially reduces the -printed output to stdout during the copying process and is much -faster. We prefer this plugin since we are copying folders around -for the API documentation. -""" -from shutil import copytree, ignore_patterns, rmtree -import os -from pathlib import Path - -from nikola.plugin_categories import Task -from nikola.utils import config_changed - - -class CopyTree(Task): - """Copy an entire tree of files.""" - - name = "copy_tree" - - def gen_tasks(self): - """Copy docs files into the output folder.""" - # Put these into a dictionary so that if they change, - # the task is marked as out-of-date - kw = { - "docs_folders": self.site.config["DOCS_FOLDERS"], - "output_folder": self.site.config["OUTPUT_FOLDER"], - } - - # Ensure this task is created even if nothing needs to be done - yield self.group_task() - - def copytree_task(src, dst, ignore): - if os.path.exists(dst): - rmtree(dst) - - copytree(src=src, dst=dst, ignore=ignore) - - for src, rel_dst in kw["docs_folders"].items(): - final_dst = os.path.join(kw["output_folder"], rel_dst) - all_files = [i for i in Path(src).glob("**/*") if not i.is_dir()] - yield { - "basename": self.name, - "name": rel_dst, - "targets": [final_dst], - "uptodate": [config_changed(kw, "copy_tree")], - "file_dep": all_files, - "actions": [ - ( - copytree_task, - [], - { - "src": src, - "dst": final_dst, - "ignore": ignore_patterns("*.md5", "*.map"), - }, - ) - ], - } diff --git a/plugins/new_release.plugin b/plugins/new_release.plugin deleted file mode 100644 index 0014f88ea..000000000 --- a/plugins/new_release.plugin +++ /dev/null @@ -1,8 +0,0 @@ -[Core] -Name = new_release -Module = new_release - -[Documentation] -Author = Paul Blum -Version = 1.0 -Description = Add release notes for the latest version of Cantera to the site diff --git a/plugins/new_release.py b/plugins/new_release.py deleted file mode 100644 index c3b97ba5e..000000000 --- a/plugins/new_release.py +++ /dev/null @@ -1,142 +0,0 @@ -"""Add release notes for the latest version of Cantera to the site. - -This command plugin performs the following actions: - -1. Creates a markdown page containing the body content of the latest Cantera release on -Github (other release versions can be manually specified via options). The page will be -created in 'pages/documentation/release_notes' as '{release tag_name}.md'. - -2. Modifies 'pages/documentation/index.html' by adding an entry to the 'Release Notes' -card. The entry will be titled '{release name}' and will link to the markdown page -created in (1). -""" - -import re -from git import Repo -from nikola.plugin_categories import Command -import requests -from datetime import datetime -from pathlib import Path -from nikola import utils -from lxml import etree, html - -CANTERA_WEBSITE = Path(__file__).parent.parent - - -def expand_cantera_commits(text): - """Replaces shorthand Cantera commit references with their full-length hashes""" - cantera_repo = Repo(Path.cwd().parent / "cantera") - commits = cantera_repo.iter_commits("main") - commit_map = {c.hexsha[:7]: c.hexsha for c in commits} - pattern = re.compile(r"(?<=\W)[a-z0-9]{7}(?=\W)") - - def expand_commits(string): - match = pattern.search(string) - if match is None: - return string - key, start, end = match.group(), match.start(), match.end() - if key in commit_map: - return string[:start] + commit_map[key] + expand_commits(string[end:]) - return string[:end] + expand_commits(string[end:]) - - return expand_commits(text) - - -class NewRelease(Command): - name = "new_release" - doc_usage = "[options]" - - cmd_options = [ - { - "name": "tag_name", - "short": "t", - "long": "tag", - "type": str, - "default": None, - "help": "Tag name of desired release", - }, - { - "name": "release_id", - "short": "i", - "long": "id", - "type": str, - "default": "latest", - "help": "Release ID of desired release", - }, - ] - - def _execute(self, options, args): - """Add release notes for the latest version of Cantera to the site.""" - - # Get JSON-formatted details of the Cantera release from the Github Releases API - if options["tag_name"] is not None: - urlpath = "tags/{}".format(options["tag_name"]) - else: - urlpath = options["release_id"] - - api_response = requests.get( - "https://api.github.com/repos/Cantera/cantera/releases/{}".format(urlpath) - ) - api_response.raise_for_status() - release_json = api_response.json() - - # Retrieve needed information from JSON, format the text of the new release page - title = release_json["name"] - slug = release_json["tag_name"] - newfile_name = "{}.md".format(slug) - path = Path.cwd() / "pages" / "documentation" / "release_notes" / newfile_name - iso_date = release_json["published_at"] - date = datetime.strptime(iso_date, "%Y-%m-%dT%H:%M:%S%z").strftime("%B %-d, %Y") - release_text = expand_cantera_commits(release_json["body"]) - # Nikola doesn't convert <details> or <summary> tags correctly... Remove any - # lines that begin with those tags via the following command: - release_text = re.sub( - r"^\s*</?(summary|details).*$", "", release_text, flags=re.MULTILINE - ) - end_of_firstline = release_text.find("\n") - release_text = ( - release_text[:end_of_firstline] - + "\n\nPublished on {} | [Full release on Github]" - "(https://github.com/Cantera/cantera/releases/tag/{})".format(date, slug) - + release_text[end_of_firstline:] - ) - release_text = release_text.replace("\r\n", "\n").replace("\r", "\n") - - # Create a new markdown page with the formatted release information - self.site.plugin_manager.getPluginByName( - "markdown", "PageCompiler" - ).plugin_object.create_post( - path, - content=release_text, - onefile=True, - title=title, - slug=slug, - date=iso_date, - is_page=True, - ) - # Notify the user of the newly created page - pagelogger = utils.get_logger("new_page") - pagelogger.info("{} was created at {}".format(newfile_name, path)) - - # Add a link to the new page to the site's Documentation page - indexhtml_file = CANTERA_WEBSITE / "pages" / "documentation" / "index.html" - indexhtml_content = indexhtml_file.read_text(encoding="utf-8") - sections = html.fragments_fromstring(indexhtml_content) - for releasenotes_card in sections[-1].xpath('//div[@id="release-notes"]'): - new_entry = etree.Element( - "a", - { - "href": "/documentation/release_notes/{}.html".format(slug), - "class": "list-group-item release-notes", - }, - ) - new_entry.text = title - new_entry.tail = "\n " - releasenotes_card.insert(0, new_entry) - indexhtml_content = "".join( - [etree.tostring(section, encoding="unicode") for section in sections] - ) - indexhtml_file.write_text(indexhtml_content) - # Notify the user that the Documentation page was modified - pagelogger = utils.get_logger("modified_page") - pagelogger.info("{} was modified".format(indexhtml_file)) diff --git a/plugins/override_html_formatter.plugin b/plugins/override_html_formatter.plugin deleted file mode 100644 index fb936391a..000000000 --- a/plugins/override_html_formatter.plugin +++ /dev/null @@ -1,8 +0,0 @@ -[Core] -Name = override_html_formatter -Module = override_html_formatter - -[Documentation] -Author = Paul Blum -Version = 1.0 -Description = Override Nikola's modification of the Pygments HTML Formatter. diff --git a/plugins/override_html_formatter.py b/plugins/override_html_formatter.py deleted file mode 100644 index eb7eabe57..000000000 --- a/plugins/override_html_formatter.py +++ /dev/null @@ -1,35 +0,0 @@ -"""Override Nikola's modification of the Pygments HTML Formatter, -reverting it back to the unmodified version. - -Any attempted initialization of a NikolaPygmentsHTML object (from the nikola.utils -package) for codeblock to HTML formatting will now result in the initialization of -a default HtmlFormatter object (from the pygments.formatters package). - -To create a codeblock to HTML formatter with nondefault options, -call pygments.formatters.HtmlFormatter([options]) -""" -from nikola.plugin_categories import RestExtension -from pygments.formatters import HtmlFormatter -import nikola.utils - - -class OverrideHTMLFormatter(RestExtension): - """Override Nikola's modification of the Pygments HTML Formatter, - reverting it back to the unmodified version.""" - - name = "override_html_formatter" - - def set_site(self, site): - """Set the Nikola site.""" - self.site = site - nikola.utils.NikolaPygmentsHTML = PygmentsHtmlFormatter - return super().set_site(site) - - -class PygmentsHtmlFormatter(HtmlFormatter): - """The default version of the Pygments HTML Formatter.""" - - def __init__(self, *args, **kwargs): - """Initialize the formatter with default options, - no matter what options Nikola passes it.""" - super().__init__() diff --git a/plugins/parse_docs.plugin b/plugins/parse_docs.plugin deleted file mode 100644 index 3183c3f0a..000000000 --- a/plugins/parse_docs.plugin +++ /dev/null @@ -1,8 +0,0 @@ -[Core] -Name = parse_docs -Module = parse_docs - -[Documentation] -Author = Bryan Weber -Version = 0.1 -Description = Parse the Cantera documentation to build link trees diff --git a/plugins/parse_docs.py b/plugins/parse_docs.py deleted file mode 100644 index 89fa72325..000000000 --- a/plugins/parse_docs.py +++ /dev/null @@ -1,117 +0,0 @@ -"""Parse the documentation to allow Sphinx-style docs references. - -This plugin allows referring to other locations in the documentation -with ``:class:`` style references. -""" -from pathlib import Path - -from nikola.plugin_categories import Task -from nikola.utils import get_logger -from lxml.html import tostring, parse - -class ParseDocs(Task): - """Parse the documentation to find link targets.""" - - name = "parse_docs" - - def set_site(self, site): - """Set up the Nikola site instance for this plugin.""" - self.site = site - - # Ensure that this Task is run before the posts are rendered - # We need to enforce this order because rendering the posts - # requires the targets that we generate here - self.inject_dependency("render_posts", self.name) - - self.logger = get_logger(self.name) - self.site.cython_targets = {} - self.site.cti_targets = {} - self.site.matlab_targets = {} - - self.kw = { - "output_folder": site.config["OUTPUT_FOLDER"], - "docs_folders": site.config["DOCS_FOLDERS"], - "cantera_version": site.config["CANTERA_VERSION"], - } - - return super(ParseDocs, self).set_site(site) - - def gen_tasks(self): - """Generate the tasks to be done.""" - # Ensure that this task is created, even if nothing needs to be done - yield self.group_task() - - def process_targets(dirname, base_dir, docs_folder): - files = (base_dir / dirname).glob("*.html") - - target_name = "{}_targets".format(dirname) - targets_dict = getattr(self.site, target_name) - - duplicate_targets = [] - - for f_path in files: - f_path = Path(f_path) - with open(f_path, "r", encoding="utf8") as html_file: - tree = parse(html_file) - - location = str(f_path.relative_to(docs_folder)) - for elem in tree.xpath("//dt"): - if elem.get("id") is None: - continue - - elem_id = elem.get("id") - parts = elem_id.split(".") - try: - # This pattern worked for the Cantera 2.5.1 docs - node = elem.xpath('code[contains(concat(" ", @class, " "), " descname ")]') - if not len(node): - # Output from Sphinx 4.4.0 seems to fit this pattern - node = elem.xpath('span[contains(concat(" ", @class, " "), " descname ")]')[0] - title = node[0].text - except IndexError as err: - self.logger.error( - "Unknown title for class: {}\n{}".format(err, - tostring(elem)) - ) - title = parts[-1] - - targets = [".".join(parts[x:]) for x in range(len(parts))] - for target in targets: - # Don't allow targets that are duplicated within a context - # This means we can't link to overloaded attributes with the - # :class: role and the unqualified name, but it's not clear - # where those should link anyways. You can always use the - # qualified name such as ClassName.property - if target in duplicate_targets: - continue - elif target in targets_dict: - duplicate_targets.append(target) - targets_dict.pop(target) - else: - targets_dict[target] = (location, elem_id, title) - - cached_target = self.site.cache.get(target_name) - if cached_target is not None: - cached_target.update(getattr(self.site, target_name)) - self.site.cache.set(target_name, cached_target) - else: - self.site.cache.set(target_name, getattr(self.site, target_name)) - - output_folder = Path(self.kw["output_folder"]) - cantera_version = self.kw["cantera_version"] - docs_folder = self.kw["docs_folders"][ - "api-docs/docs-{}".format(cantera_version) - ] - - base_dir = output_folder / docs_folder / "sphinx" / "html" - - dirs = ("cython", "matlab", "cti") - for dirname in dirs: - yield { - "basename": self.name, - "name": dirname, - "task_dep": ["copy_tree"], - "actions": [ - (process_targets, [dirname, base_dir, output_folder / docs_folder]) - ], - } diff --git a/plugins/process_ref_targets.plugin b/plugins/process_ref_targets.plugin deleted file mode 100644 index 1770f51d6..000000000 --- a/plugins/process_ref_targets.plugin +++ /dev/null @@ -1,8 +0,0 @@ -[Core] -name = process_ref_targets -module = process_ref_targets - -[Documentation] -author = Bryan Weber -version = 1.0 -documentation = Process the reST targets that can be pointed to by :ref: diff --git a/plugins/process_ref_targets.py b/plugins/process_ref_targets.py deleted file mode 100644 index 54174822e..000000000 --- a/plugins/process_ref_targets.py +++ /dev/null @@ -1,203 +0,0 @@ -"""Find and process reference targets in reST files. - -References in reST files can be in the form ``:ref:``. -This module processes labels in the form of - -.. code:: rest - - .. labelname: - -and stores the resulting page location and anchor tag for the -label. This information is stored in the ``site.ref_targets`` -and ``site.anon_ref_targets` attributes. -""" -from nikola.plugin_categories import Task -from nikola.utils import get_logger, config_changed -from docutils.io import StringInput, StringOutput -from docutils import nodes -from docutils.readers.standalone import Reader -from docutils.core import Publisher -from copy import copy - -from pathlib import Path -import tempfile -import requests - -HERE = Path(__file__).parent - - -class ProcessRefTargets(Task): - """Find and process targets in reST files.""" - - name = "process_ref_targets" - - def set_site(self, site): - """Set the Nikola site instance for this plugin.""" - self.site = site - self.logger = get_logger(self.name) - self.site.anon_ref_targets = {} - self.site.ref_targets = {} - # This attribute is set to True when the targets are being - # processed to avoid spurious warnings about missing targets - self.site.processing_targets = False - - # Ensure that this Task is run before the posts are rendered - # We need to enforce this order because rendering the posts - # requires the targets that we generate here - self.inject_dependency("render_posts", self.name) - - return super(ProcessRefTargets, self).set_site(site) - - def gen_tasks(self): - """Generate the set of processing tasks.""" - self.site.scan_posts() - kw = { - "translations": self.site.config["TRANSLATIONS"], - "timeline": self.site.timeline, - } - self.tl_changed = False - # Ensure that this task is created, even if nothing needs to be done - yield self.group_task() - - def tl_ch(): - self.tl_changed = True - - yield { - "basename": self.name, - "name": "timeline_changes", - "actions": [tl_ch], - "uptodate": [config_changed({1: kw["timeline"]})], - } - - for lang in kw["translations"]: - deps_dict = copy(kw) - deps_dict.pop("timeline") - for post in self.site.timeline: - if not post.source_ext() == ".rst": - continue - source = post.translated_source_path(lang) - task = { - "basename": self.name, - "name": source, - "task_dep": ["process_ref_targets:timeline_changes"], - "actions": [ - ( - process_targets, - [self.site, self.logger, source, post.permalink()], - ), - (update_cache, [self.site]), - ], - } - yield task - - # These are YAML API docs. They are parsed here because they aren't - # the typical Sphinx-generated documentation for functions and - # classes, most of the text is broken out into sections with ref - # targets. - cantera_version = self.site.config["CANTERA_VERSION"] - yaml_rst_path = f"api-docs/docs-{cantera_version}/sphinx/html/_sources/yaml" - for rest_file in Path(yaml_rst_path).glob("**/*.rst.txt"): - stem = rest_file.name.split('.')[0] - permalink = (f"/documentation/docs-{cantera_version}" - f"/sphinx/html/yaml/{stem}.html" - ) - yield { - "basename": self.name, - "name": str(rest_file), - "task_dep": ["process_ref_targets:timeline_changes"], - "actions": [ - ( - process_targets, - [self.site, self.logger, str(rest_file), permalink], - ), - (update_cache, [self.site]), - ], - } - - -def update_cache(site): - """Update the Nikola build cache.""" - cached_targets = site.cache.get("ref_targets") - anon_cached_targets = site.cache.get("anon_ref_targets") - if cached_targets is not None: - cached_targets.update(site.ref_targets) - site.cache.set("ref_targets", cached_targets) - else: - site.cache.set("ref_targets", site.ref_targets) - - if anon_cached_targets is not None: - anon_cached_targets.update(site.anon_ref_targets) - site.cache.set("anon_ref_targets", anon_cached_targets) - else: - site.cache.set("anon_ref_targets", site.anon_ref_targets) - - -def process_targets(site, logger, source, permalink): - """Process the target locations in the reST files.""" - site.processing_targets = True - reader = Reader() - reader.l_settings = {"source": source} - with open(source, "r", encoding="utf8") as in_file: - data = in_file.read() - pub = Publisher( - reader=reader, - parser=None, - writer=None, - settings=None, - source_class=StringInput, - destination_class=StringOutput, - ) - pub.set_components(None, "restructuredtext", "html") - # Reading the file will generate output/errors that we don't care about - # at this stage. The report_level = 5 means no output - pub.process_programmatic_settings( - settings_spec=None, settings_overrides={"report_level": 5}, config_section=None - ) - pub.set_source(data, None) - pub.set_destination(None, None) - pub.publish() - document = pub.document - site.processing_targets = False - - # Code based on Sphinx std domain - for name, is_explicit in document.nametypes.items(): - if not is_explicit: - continue - labelid = document.nameids[name] - if labelid is None: - continue - node = document.ids[labelid] - if node.tagname == "target" and "refid" in node: - node = document.ids.get(node["refid"]) - labelid = node["names"][0] - if ( - node.tagname == "footnote" - or "refuri" in node - or node.tagname.startswith("desc_") - ): - continue - if name in site.ref_targets: - logger.warn( - "Duplicate label {dup}, other instance in {other}".format( - dup=name, other=site.ref_targets[name][0] - ) - ) - site.anon_ref_targets[name] = permalink, labelid - - def clean_astext(node): - """Like node.astext(), but ignore images. - - Taken from sphinx.util.nodes - """ - node = node.deepcopy() - for img in node.traverse(nodes.image): - img["alt"] = "" - for raw in node.traverse(nodes.raw): - raw.parent.remove(raw) - return node.astext() - - if node.tagname in ("section", "rubric"): - sectname = clean_astext(node[0]) - else: - continue - site.ref_targets[name] = permalink, labelid, sectname diff --git a/plugins/ref.plugin b/plugins/ref.plugin deleted file mode 100644 index 1f8a7240e..000000000 --- a/plugins/ref.plugin +++ /dev/null @@ -1,12 +0,0 @@ -[Core] -name = rest_ref -module = ref - -[Nikola] -compiler = rest -PluginCategory = CompilerExtension - -[Documentation] -author = Bryan Weber -version = 0.1 -description = Role to link to a :ref: to a target (processed from process_ref_targets) from another document diff --git a/plugins/ref.py b/plugins/ref.py deleted file mode 100644 index 23de209b1..000000000 --- a/plugins/ref.py +++ /dev/null @@ -1,99 +0,0 @@ -"""Parser for :ref: role. - -This plugin is an extension for the reST parser in Nikola that looks -for the ``:ref:`` role and replaces that reference with a link node -to the appropriate target from the `process_ref_targets` plugin. -""" - -from docutils import nodes -from docutils.parsers.rst import roles - -from nikola.utils import split_explicit_title, get_logger -from nikola.plugin_categories import RestExtension - -LOGGER = get_logger("rest_ref") - - -class Plugin(RestExtension): - """Plugin for ref role.""" - - name = "rest_ref" - - def set_site(self, site): - """Set Nikola site.""" - self.site = site - roles.register_canonical_role("ref", ref_role) - ref_role.site = site - return super(Plugin, self).set_site(site) - - -def _ref_link(rawtext, text, options={}, content=[]): - """Handle the ref role.""" - # If we're just processing the targets, ignore the role - if ref_role.site.processing_targets: - return True, True, None, None, None - - has_explicit_title, title, target = split_explicit_title(text) - target = target.lower() - - if ref_role.site.cache.get("ref_targets") is not None: - ref_targets = ref_role.site.cache.get("ref_targets").copy() - else: - ref_targets = ref_role.site.ref_targets.copy() - - if ref_role.site.cache.get("anon_ref_targets") is not None: - anon_ref_targets = ref_role.site.cache.get("anon_ref_targets").copy() - else: - anon_ref_targets = ref_role.site.anon_ref_targets.copy() - - if target not in ref_targets and ( - target in anon_ref_targets and not has_explicit_title - ): - LOGGER.error("Anonymous targets must have a link text: {}".format(target)) - return False, False, None, None, target - elif target in anon_ref_targets: - permalink = anon_ref_targets[target][0] - if permalink.endswith("/"): - permalink += "index.html" - - permalink += "#" + target - - return True, False, title, permalink, target - else: - LOGGER.error("Unknown reference target: {}".format(target)) - return False, False, None, None, target - - if target not in ref_targets: - LOGGER.error("Unknown reference target: {}".format(target)) - return False, False, None, None, target - - permalink = ref_targets[target][0] - if permalink.endswith("/"): - permalink += "index.html" - if not has_explicit_title: - title = ref_targets[target][2] - - permalink += "#" + target - - return True, False, title, permalink, target - - -def ref_role(name, rawtext, text, lineno, inliner, options={}, content=[]): - """Handle the ref role. - - The function signature here is a standard signature for roles in reST plugins. - """ - success, processing, title, permalink, target = _ref_link( - rawtext, text, options, content - ) - if processing: - return [nodes.raw("", text, format="html")], [] - if success: - node = nodes.reference(rawtext, title, refuri=permalink, *options) - return [node], [] - else: - msg = inliner.reporter.warning( - 'Unknown reference target: {0}"'.format(target), line=lineno - ) - prb = inliner.problematic(rawtext, rawtext, msg) - return [prb], [msg] diff --git a/plugins/render_cxx_examples.plugin b/plugins/render_cxx_examples.plugin deleted file mode 100644 index ed1dfdfcb..000000000 --- a/plugins/render_cxx_examples.plugin +++ /dev/null @@ -1,8 +0,0 @@ -[Core] -Name = render_cxx_examples -Module = render_cxx_examples - -[Documentation] -Author = Ray Speth -Version = 0.1 -Description = Build the Cantera C++ examples into the output diff --git a/plugins/render_cxx_examples.py b/plugins/render_cxx_examples.py deleted file mode 100644 index 87773ad6d..000000000 --- a/plugins/render_cxx_examples.py +++ /dev/null @@ -1,279 +0,0 @@ -"""Render the C++ examples from the Cantera repository into Nikola listings. - -This plugin renders C++ examples from the main Cantera repository into the -examples/cpp output folder. It looks for the examples in the folder configured -in the top-level conf.py file in the ``EXAMPLES_FOLDERS`` dictionary. That -dictionary has keys with the source folder and values with the destination -folder (relative to the ``OUTPUT_FOLDER``). The relevant source folder is found -as the key associated with the value that contains the string ``cxx``, -typically ``"../cantera/samples/cxx": "examples/cxx"``. -""" -from pathlib import Path - -from nikola.plugin_categories import Task -from nikola import utils -from pygments import highlight -from pygments.lexers import CppLexer -from itertools import chain -import re -import natsort - - -def render_example_index(site, kw, headers, output_file): - """Render the index of all of the C++ examples. - - Parameters - ========== - site: - An instance of a Nikola site, available in any plugin as ``self.site`` - kw: - A dictionary of keywords for this task - headers: - A dictionary of the example categories and the summaries of each example - output_file: - A pathlib.Path instance representing the output file that will be rendered - - """ - n = 3 - for head_dict in headers.values(): - head_files = head_dict["names"] - head_dict["names"] = [ - head_files[i : i + n] for i in range(0, len(head_files), n) # NOQA: E203 - ] - - permalink = output_file.relative_to(kw["output_folder"]) - title = "C++ Examples" - context = { - "headers": headers, - "lang": kw["default_lang"], - "pagekind": ["example"], - "permalink": str(permalink), - "title": title, - "description": title, - } - site.render_template("cxx-example-index.tmpl", str(output_file), context) - - -def render_example(site, kw, in_names, out_name): - """Render a set of .h and .cpp files to HTML with formatting. - - Parameters - ========== - site: - An instance of a Nikola site, available in any plugin as ``self.site`` - kw: - A dictionary of keywords for this task - in_names: - The files to be rendered, as a list of pathlib.Path objects - out_name: - A pathlib.Path instance pointing to the rendered output file - - """ - items = [] - for source_file in in_names: - code = highlight( - source_file.read_bytes(), - CppLexer(), - utils.NikolaPygmentsHTML(source_file.name) - ) - items.append({ - "code": code, - "title": source_file.name, - "source_link": source_file.name, - }) - - context = { - "items": items, - "title": out_name, - "lang": kw["default_lang"], - "pagekind": ["example"], - } - site.render_template("multifile-example.tmpl", str(out_name), context) - - -class RenderCxxExamples(Task): - """Render the C++ examples with a Nikola Task. - - As with all Nikola ``Tasks``, the key method here is the ``gen_tasks`` - method, which yields dictionaries that represent tasks that doit needs - to run. There are two primary kinds of tasks, one that renders each - example file, and one that renders an index of all of the examples. - """ - - name = "render_cxx_examples" - - def set_site(self, site): - """Set Nikola site.""" - # Verify that a C++ output folder appears only once in EXAMPLES_FOLDERS - found_cxx = False - for source, dest in site.config["EXAMPLES_FOLDERS"].items(): - if "cxx" in dest: - if found_cxx: - self.logger.error( - "More than one folder to output C++ examples was found in " - "EXAMPLES_FOLDERS, exiting" - ) - else: - found_cxx = True - self.input_folder = source - self.examples_folder = dest - - if not found_cxx: - self.logger.warn( - "Didn't find an output folder for C++ examples in EXAMPLES_FOLDERS" - ) - - return super().set_site(site) - - def gen_tasks(self): - """Render examples.""" - kw = { - "default_lang": self.site.config["DEFAULT_LANG"], - "examples_folders": self.site.config["EXAMPLES_FOLDERS"], - "output_folder": Path(self.site.config["OUTPUT_FOLDER"]), - "index_file": self.site.config["INDEX_FILE"], - "strip_indexes": self.site.config["STRIP_INDEXES"], - } - - yield self.group_task() - - # When any key or value in the uptodate dictionary changes, the - # examples pages need to be rebuilt. - uptodate = {"c": self.site.GLOBAL_CONTEXT} - - for k, v in self.site.GLOBAL_CONTEXT["template_hooks"].items(): - uptodate["||template_hooks|{0}||".format(k)] = v.calculate_deps() - - for k in self.site._GLOBAL_CONTEXT_TRANSLATABLE: - uptodate[k] = self.site.GLOBAL_CONTEXT[k](kw["default_lang"]) - - # save navigation links as dependencies - uptodate["nav_links"] = uptodate["c"]["navigation_links"](kw["default_lang"]) - - uptodate["kw"] = kw - - examples_template_deps = self.site.template_system.template_deps( - "examples.tmpl" - ) - - index_template_deps = self.site.template_system.template_deps( - "cxx-example-index.tmpl" - ) - folder = Path(self.input_folder).resolve() - cxx_examples = { - subdir: list(chain(subdir.glob("*.h"), subdir.glob("*.cpp"))) - for subdir in folder.glob("*") - } - cxx_headings = { - "examples": { - "name": "Examples", - "names": [], - "titles": {}, - "summaries": {}, - } - } - - uptodate["d"] = cxx_headings.keys() - uptodate["f"] = list(map(str, cxx_examples)) - - - for subdir, cxx_ex_files in cxx_examples.items(): - if not cxx_ex_files: - # Skip items that are not directories containing C++ files - continue - - # Take the first non-empty, non "@file..." line as the title. - # Take the following comments, up to the next blank line - # (not including comment characters) as the summary. - doc = [] - def append_doc(line): - line = line.lstrip('/* !') - if line.startswith('@file'): - line = re.sub(r'@file \w+.\w+\s*', '', line) - doc.append(line) - - for ex_file in cxx_ex_files: - if not ex_file.name.endswith('.cpp'): - continue - in_block_comment = False - for line in ex_file.read_text(encoding="utf-8").split("\n"): - line = line.strip() - if '*/' in line: - in_block_comment = False - append_doc(line[:line.find('*/')]) - elif line.startswith('/*'): - in_block_comment = True - append_doc(line) - elif in_block_comment or line.startswith("//") or line.startswith('* '): - append_doc(line) - elif any(doc): - break - - title = '' - summary = [] - for line in doc: - if line and not title: - title = line - elif line: - summary.append(line) - elif summary: - break - summary = ' '.join(summary) - if not summary: - self.logger.warn( - f"The C++ example {ex_file!s} doesn't have an appropriate summary" - ) - name = subdir.stem.replace('_', '-') - - cxx_headings["examples"]["names"].append(name) - cxx_headings["examples"]["titles"][name] = title - cxx_headings["examples"]["summaries"][name] = summary - out_name = kw["output_folder"].joinpath( - self.examples_folder, name + '.html' - ) - - yield { - "basename": self.name, - "name": str(out_name), - "file_dep": examples_template_deps + cxx_ex_files, - "targets": [out_name], - "actions": [(render_example, [self.site, kw, cxx_ex_files, out_name])], - # This is necessary to reflect changes in blog title, - # sidebar links, etc. - "uptodate": [utils.config_changed(uptodate, "cxx_examples:source")], - "clean": True, - } - - for ex_file in cxx_ex_files: - out_name = kw["output_folder"].joinpath( - self.examples_folder, ex_file.name - ) - yield { - "basename": self.name, - "name": str(out_name), - "file_dep": cxx_ex_files, - "targets": [out_name], - "actions": [(utils.copy_file, [ex_file, out_name])], - "clean": True, - } - - cxx_headings["examples"]["names"] = natsort.natsorted( - cxx_headings["examples"]["names"], alg=natsort.IC - ) - - out_name = kw["output_folder"].joinpath(self.examples_folder, kw["index_file"]) - - all_files = [str(name[0]) for name in chain(cxx_examples.values()) if name] - yield { - "basename": self.name, - "name": str(out_name), - "file_dep": index_template_deps + all_files, - "targets": [out_name], - "actions": [ - (render_example_index, [self.site, kw, cxx_headings, out_name]) - ], - # This is necessary to reflect changes in blog title, - # sidebar links, etc. - "uptodate": [utils.config_changed(uptodate, "cxx_examples:folder")], - "clean": True, - } diff --git a/plugins/render_fortran_examples.plugin b/plugins/render_fortran_examples.plugin deleted file mode 100644 index 113c89386..000000000 --- a/plugins/render_fortran_examples.plugin +++ /dev/null @@ -1,8 +0,0 @@ -[Core] -Name = render_fortran_examples -Module = render_fortran_examples - -[Documentation] -Author = Ray Speth -Version = 0.1 -Description = Build the Cantera Fortran examples into the output diff --git a/plugins/render_fortran_examples.py b/plugins/render_fortran_examples.py deleted file mode 100644 index 123a1e23f..000000000 --- a/plugins/render_fortran_examples.py +++ /dev/null @@ -1,278 +0,0 @@ -"""Render the Fortran examples from the Cantera repository into Nikola listings. - -This plugin renders Fortran examples from the main Cantera repository into the -examples/fortran output folder. It looks for the examples in the folder configured -in the top-level conf.py file in the ``EXAMPLES_FOLDERS`` dictionary. That -dictionary has keys with the source folder and values with the destination -folder (relative to the ``OUTPUT_FOLDER``). The relevant source folder is found -as the key associated with the value that contains the string ``fortran``, -typically ``"../cantera/samples/f90": "examples/fortran"``. -""" -from pathlib import Path - -from nikola.plugin_categories import Task -from nikola import utils -from pygments import highlight -from pygments.lexers import FortranLexer, FortranFixedLexer, CppLexer -from itertools import chain -import re -import natsort - - -def render_example_index(site, kw, headers, output_file): - """Render the index of all of the Fortran examples. - - Parameters - ========== - site: - An instance of a Nikola site, available in any plugin as ``self.site`` - kw: - A dictionary of keywords for this task - headers: - A dictionary of the example categories and the summaries of each example - output_file: - A pathlib.Path instance representing the output file that will be rendered - - """ - n = 3 - for head_dict in headers.values(): - head_files = head_dict["files"] - head_dict["files"] = [ - head_files[i : i + n] for i in range(0, len(head_files), n) # NOQA: E203 - ] - - permalink = output_file.relative_to(kw["output_folder"]) - title = "Fortran Examples" - context = { - "headers": headers, - "lang": kw["default_lang"], - "pagekind": ["example"], - "permalink": str(permalink), - "title": title, - "description": title, - } - site.render_template("fortran-example-index.tmpl", str(output_file), context) - - -def render_example(site, kw, in_name, out_name): - """Render a single source file to HTML with formatting. - - Parameters - ========== - site: - An instance of a Nikola site, available in any plugin as ``self.site`` - kw: - A dictionary of keywords for this task - in_name: - The file to be rendered, as an instance of pathlib.Path - out_name: - A pathlib.Path instance pointing to the rendered output file - - """ - if str(in_name).endswith('.cpp'): - lexer = CppLexer() - elif str(in_name).endswith('.f'): - lexer = FortranFixedLexer() - else: - lexer = FortranLexer() - code = highlight( - in_name.read_bytes(), lexer, utils.NikolaPygmentsHTML(in_name.name) - ) - - title = in_name.name - permalink = out_name.relative_to(kw["output_folder"]) - source_link = permalink.stem # remove '.html' - context = { - "code": code, - "title": title, - "permalink": str(permalink), - "lang": kw["default_lang"], - "description": title, - "source_link": source_link, - "pagekind": ["example"], - } - site.render_template("examples.tmpl", str(out_name), context) - - -class RenderFortranExamples(Task): - """Render the Fortran examples with a Nikola Task. - - As with all Nikola ``Tasks``, the key method here is the ``gen_tasks`` - method, which yields dictionaries that represent tasks that doit needs - to run. There are two primary kinds of tasks, one that renders each - example file, and one that renders an index of all of the examples. - """ - - name = "render_fortran_examples" - - def set_site(self, site): - """Set Nikola site.""" - # Verify that an output folder appears only once in EXAMPLES_FOLDERS - found_fortran = False - for source, dest in site.config["EXAMPLES_FOLDERS"].items(): - if "fortran" in dest: - if found_fortran: - self.logger.error( - "More than one folder to output Fortran examples was found in " - "EXAMPLES_FOLDERS, exiting" - ) - else: - found_fortran = True - self.input_folder = source - self.examples_folder = dest - - if not found_fortran: - self.logger.warn( - "Didn't find an output folder for Fortran examples in EXAMPLES_FOLDERS" - ) - - return super().set_site(site) - - def gen_tasks(self): - """Render examples.""" - kw = { - "default_lang": self.site.config["DEFAULT_LANG"], - "examples_folders": self.site.config["EXAMPLES_FOLDERS"], - "output_folder": Path(self.site.config["OUTPUT_FOLDER"]), - "index_file": self.site.config["INDEX_FILE"], - "strip_indexes": self.site.config["STRIP_INDEXES"], - } - - yield self.group_task() - - # When any key or value in the uptodate dictionary changes, the - # examples pages need to be rebuilt. - uptodate = {"c": self.site.GLOBAL_CONTEXT} - - for k, v in self.site.GLOBAL_CONTEXT["template_hooks"].items(): - uptodate["||template_hooks|{0}||".format(k)] = v.calculate_deps() - - for k in self.site._GLOBAL_CONTEXT_TRANSLATABLE: - uptodate[k] = self.site.GLOBAL_CONTEXT[k](kw["default_lang"]) - - # save navigation links as dependencies - uptodate["nav_links"] = uptodate["c"]["navigation_links"](kw["default_lang"]) - - uptodate["kw"] = kw - - examples_template_deps = self.site.template_system.template_deps( - "examples.tmpl" - ) - - index_template_deps = self.site.template_system.template_deps( - "fortran-example-index.tmpl" - ) - folder = Path(self.input_folder).resolve() - fortran_examples = list(chain( - folder.glob("*.f90"), - folder.glob("../f77/*.f"), # hack to combine all Fortran samples on one page - folder.glob("../f77/*.cpp"), - )) - fortran_headers = { - "examples": { - "name": "Examples", - "files": [], - "titles": {}, - "summaries": {}, - } - } - - uptodate["d"] = fortran_headers.keys() - uptodate["f"] = list(map(str, fortran_examples)) - - for fortran_ex_file in fortran_examples: - # Take the first non-empty, non "@file..." line as the title. - # Take the following comments, up to the next blank line - # (not including comment characters) as the summary. - # Combination of detection for F77, F90, and C/C++ comments. - fortran_headers["examples"]["files"].append(fortran_ex_file) - doc = [] - def append_doc(line): - line = line.lstrip('/* !') - if line.startswith('@file'): - line = re.sub(r'@file \w+.\w+\s*', '', line) - doc.append(line) - - in_block_comment = False - for line in fortran_ex_file.read_text(encoding="utf-8").split("\n"): - line = line.strip() - if '*/' in line: - in_block_comment = False - append_doc(line[:line.find('*/')]) - if line.startswith('/*'): - append_doc(line) - in_block_comment = True - if (in_block_comment or line.startswith('!') or line.startswith("//") - or line.startswith('* ')): - append_doc(line) - elif line.startswith('c '): - append_doc(line[6:]) - elif line == 'c': - append_doc('') - elif any(doc): - break - - title = '' - summary = [] - for line in doc: - if line and not title: - title = line - elif line: - summary.append(line) - elif summary: - break - summary = ' '.join(summary) - - if not summary: - self.logger.warn( - f"The Fortran example {fortran_ex_file!s} doesn't have " - "an appropriate summary." - ) - fortran_headers["examples"]["summaries"][fortran_ex_file.name] = summary - fortran_headers["examples"]["titles"][fortran_ex_file.name] = title - out_name = kw["output_folder"].joinpath( - self.examples_folder, fortran_ex_file.name + '.html' - ) - - yield { - "basename": self.name, - "name": str(out_name), - "file_dep": examples_template_deps + [fortran_ex_file], - "targets": [out_name], - "actions": [(render_example, [self.site, kw, fortran_ex_file, out_name])], - # This is necessary to reflect changes in blog title, - # sidebar links, etc. - "uptodate": [utils.config_changed(uptodate, "fortran_examples:source")], - "clean": True, - } - - out_name = kw["output_folder"].joinpath( - self.examples_folder, fortran_ex_file.name - ) - yield { - "basename": self.name, - "name": str(out_name), - "file_dep": [fortran_ex_file], - "targets": [out_name], - "actions": [(utils.copy_file, [fortran_ex_file, out_name])], - "clean": True, - } - - fortran_headers["examples"]["files"] = natsort.natsorted( - fortran_headers["examples"]["files"], alg=natsort.IC - ) - - out_name = kw["output_folder"].joinpath(self.examples_folder, kw["index_file"]) - yield { - "basename": self.name, - "name": str(out_name), - "file_dep": index_template_deps + list(map(str, fortran_examples)), - "targets": [out_name], - "actions": [ - (render_example_index, [self.site, kw, fortran_headers, out_name]) - ], - # This is necessary to reflect changes in blog title, - # sidebar links, etc. - "uptodate": [utils.config_changed(uptodate, "fortran_examples:folder")], - "clean": True, - } diff --git a/plugins/render_jupyter_examples.plugin b/plugins/render_jupyter_examples.plugin deleted file mode 100644 index 6daf58401..000000000 --- a/plugins/render_jupyter_examples.plugin +++ /dev/null @@ -1,8 +0,0 @@ -[Core] -Name = render_jupyter_examples -Module = render_jupyter_examples - -[Documentation] -Author = Bryan Weber -Version = 0.1 -Description = Build the Cantera Jupyter examples into the output diff --git a/plugins/render_jupyter_examples.py b/plugins/render_jupyter_examples.py deleted file mode 100644 index b27a7d658..000000000 --- a/plugins/render_jupyter_examples.py +++ /dev/null @@ -1,326 +0,0 @@ -"""Render the examples from the Cantera Jupyter repository into Nikola listings. - -This plugin renders Jupyter Notebook examples from the cantera-jupyter repository -into the examples/jupyter output folder. It looks for the examples in the folder -configured in the top-level conf.py file in the ``EXAMPLES_FOLDERS`` dictionary. -That dictionary has keys with the source folder and values with the destination -folder (relative to the ``OUTPUT_FOLDER``). The relevant source folder is found -as the key associated with the value that contains the string ``jupyter``, -typically ``"../cantera-jupyter": "examples/jupyter"``. -""" -from pathlib import Path -import re -import base64 -import mimetypes - -from collections import OrderedDict -import lxml.html -import json - -from nikola.plugin_categories import Task -from nikola import utils -import natsort - - -def render_example_index(site, kw, headers, output_file): - """Render the index of all of the Jupyter examples. - - Parameters - ========== - site: - An instance of a Nikola site, available in any plugin as ``self.site`` - kw: - A dictionary of keywords for this task - headers: - A dictionary of the example categories and the summaries of each example - output_file: - A pathlib.Path instance representing the output file that will be rendered - - """ - # n is the number of examples in each row on the index page - n = 3 - for head_dict in headers.values(): - head_files = head_dict["files"] - head_dict["files"] = [ - head_files[i : i + n] for i in range(0, len(head_files), n) # NOQA: E203 - ] - - permalink = output_file.relative_to(kw["output_folder"]) - title = "Jupyter Examples" - context = { - "headers": headers, - "lang": kw["default_lang"], - "pagekind": ["example"], - "permalink": str(permalink), - "title": title, - "description": title, - } - site.render_template("jupyter-example-index.tmpl", str(output_file), context) - - -def render_example(site, kw, in_name, out_name): - """Render a single .ipynb file to HTML with formatting. - - Parameters - ========== - site: - An instance of a Nikola site, available in any plugin as ``self.site`` - kw: - A dictionary of keywords for this task - in_name: - The file to be rendered, as an instance of pathlib.Path - out_name: - A pathlib.Path instance pointing to the rendered output file - - """ - ipynb_compiler = site.plugin_manager.getPluginByName( - "ipynb", "PageCompiler" - ).plugin_object - with in_name.open(mode="r", encoding="utf-8") as in_file: - nb_json = ipynb_compiler._nbformat_read(in_file) - ipynb_raw = ipynb_compiler._compile_string(nb_json) - ipynb_html = lxml.html.fromstring(ipynb_raw) - code = lxml.html.tostring(ipynb_html, encoding="unicode") - - data_files = set() - pattern = re.compile(r"data/([\w-]+?\.\w*)") - for cell in nb_json["cells"]: - if cell["cell_type"] != "code": - continue - for match in pattern.findall(cell["source"]): - data_files.add(match) - - title = in_name.name - - permalink = out_name.relative_to(kw["output_folder"]) - source_link = permalink.stem # remove '.html' - context = { - "code": code, - "title": title, - "data_files": data_files, - "permalink": str(permalink), - "lang": kw["default_lang"], - "description": title, - "source_link": source_link, - "pagekind": ["example"], - "needs_ipython_css": True, - } - site.render_template("examples.tmpl", str(out_name), context) - - -class RenderJupyterExamples(Task): - """Render the Jupyter examples with a Nikola Task. - - As with all Nikola ``Tasks``, the key method here is the ``gen_tasks`` - method, which yields dictionaries that represent tasks that doit needs - to run. There are two primary kinds of tasks, one that renders each - example file, and one that renders an index of all of the examples. - """ - - name = "render_jupyter_examples" - - def set_site(self, site): - """Set Nikola site.""" - # Verify that a Python output folder appears only once in EXAMPLES_FOLDERS - found_jupyter = False - for source, dest in site.config["EXAMPLES_FOLDERS"].items(): - if "jupyter" in dest: - if found_jupyter: - self.logger.error( - "More than one folder to output Jupyter examples was found in " - "EXAMPLES_FOLDERS, exiting" - ) - else: - found_jupyter = True - self.input_folder = source - self.examples_folder = dest - - if not found_jupyter: - self.logger.warn( - "Didn't find an output folder for Jupyter examples in EXAMPLES_FOLDERS" - ) - - return super().set_site(site) - - def gen_tasks(self): - """Render examples.""" - kw = { - "default_lang": self.site.config["DEFAULT_LANG"], - "examples_folders": self.site.config["EXAMPLES_FOLDERS"], - "output_folder": Path(self.site.config["OUTPUT_FOLDER"]), - "index_file": self.site.config["INDEX_FILE"], - "strip_indexes": self.site.config["STRIP_INDEXES"], - "cache_folder": Path(self.site.config["CACHE_FOLDER"]), - } - - yield self.group_task() - - # When any key or value in the uptodate dictionary changes, the - # examples pages need to be rebuilt. - uptodate = {"c": self.site.GLOBAL_CONTEXT} - - for k, v in self.site.GLOBAL_CONTEXT["template_hooks"].items(): - uptodate["||template_hooks|{0}||".format(k)] = v.calculate_deps() - - for k in self.site._GLOBAL_CONTEXT_TRANSLATABLE: - uptodate[k] = self.site.GLOBAL_CONTEXT[k](kw["default_lang"]) - - # save navigation links as dependencies - uptodate["nav_links"] = uptodate["c"]["navigation_links"](kw["default_lang"]) - - uptodate["kw"] = kw - - examples_template_deps = self.site.template_system.template_deps( - "examples.tmpl" - ) - - index_template_deps = self.site.template_system.template_deps( - "jupyter-example-index.tmpl" - ) - jupyter_headers = OrderedDict( - thermo=dict(name="Thermodynamics", files=[], summaries={}, titles={}), - reactors=dict(name="Reactor Networks", files=[], summaries={}, titles={}), - flames=dict(name="One-Dimensional Flames", files=[], summaries={}, titles={}), - electrochemistry=dict(name="Electrochemistry", files=[], summaries={}, titles={}), - input=dict(name="Input Files", files=[], summaries={}, titles={}), - ) - - def get_b64_str(parent, img_fname): - img_path = parent / img_fname - b64_str = base64.b64encode(img_path.read_bytes()).decode("utf-8") - mime = mimetypes.guess_type(img_path.name)[0] - b64_str = "data:{mime};base64,{b64_str}".format(mime=mime, b64_str=b64_str) - return b64_str - - jupyter_examples = list(Path(self.input_folder).resolve().glob("*/*.ipynb")) - uptodate["d"] = jupyter_headers.keys() - uptodate["f"] = list(map(str, jupyter_examples)) - - for jpy_ex_file in jupyter_examples: - ex_category = jpy_ex_file.parent.stem - if ex_category == ".ipynb_checkpoints": - continue - if not jupyter_headers.get(ex_category, False): - self.logger.warn( - "The category {} in the Jupyter examples has no header. " - "Please add the folder to the jupyter_headers dictionary in the " - "render_jupyter_examples plugin".format(ex_category) - ) - continue - - jupyter_headers[ex_category]["files"].append(jpy_ex_file) - data = json.loads(jpy_ex_file.read_text(encoding="utf-8")) - doc = "" - title = "" - for cell in data["cells"]: - if cell["cell_type"] != "markdown": - continue - if not doc: - doc = [] - for line in cell["source"]: - if doc and title and not line.strip(): - break - if not title and line.startswith("#"): - title = line.replace("#", "").strip() - else: - doc.append(line.strip()) - doc = " ".join(doc) - for img_idx, cell_src in enumerate(cell["source"]): - if "img" in cell_src: - img = lxml.html.fromstring(cell_src) - img_fname = img.attrib["src"] - b64_str = get_b64_str(jpy_ex_file.parent, img_fname) - img.attrib["src"] = b64_str - new_img = lxml.html.tostring(img).decode("utf-8") - cell["source"][img_idx] = re.sub("<img.*/>", new_img, cell_src) - elif "![" in cell_src: - img_alt, img_fname = re.findall( - r"!\[(.*?)\]\((.*?)\)", cell_src - )[0] - if "attachment" in img_fname: - img_fname = img_fname.split(":", 1)[1] - mime = mimetypes.guess_type(img_fname)[0] - b64_src = cell["attachments"][img_fname][mime] - b64_str = "data:{mime};base64,{b64_src}".format( - mime=mime, b64_src=b64_src - ) - else: - b64_str = get_b64_str(jpy_ex_file.parent, img_fname) - - new_img = '<img src="{b64_str}" alt="{img_alt}"/>'.format( - b64_str=b64_str, img_alt=img_alt - ) - cell["source"][img_idx] = re.sub( - r"!\[.*?\]\(.*?\)", new_img, cell_src - ) - else: - continue - - cache_file = kw["cache_folder"].joinpath( - self.examples_folder, ex_category, jpy_ex_file.name - ) - cache_file.parent.mkdir(parents=True, exist_ok=True) - - with cache_file.open(mode="w", encoding="utf-8") as jfile: - json.dump(data, jfile) - - if not title or not doc: - self.logger.warn( - f"The Jupyter example {jpy_ex_file.name!s} doesn't have a parseable" - " title and/or summary" - ) - - if not title: - title = jpy_ex_file.name - - jupyter_headers[ex_category]["titles"][jpy_ex_file.name] = title - jupyter_headers[ex_category]["summaries"][jpy_ex_file.name] = doc - - out_name = kw["output_folder"].joinpath( - self.examples_folder, - ex_category, - jpy_ex_file.with_suffix(".ipynb.html").name, - ) - - yield { - "basename": self.name, - "name": str(out_name), - "file_dep": examples_template_deps + [jpy_ex_file, cache_file], - "targets": [out_name], - "actions": [(render_example, [self.site, kw, cache_file, out_name])], - # This is necessary to reflect changes in blog title, - # sidebar links, etc. - "uptodate": [utils.config_changed(uptodate, "jupyter_examples:source")], - "clean": True, - } - - out_name = kw["output_folder"].joinpath( - self.examples_folder, ex_category, jpy_ex_file.name - ) - yield { - "basename": self.name, - "name": out_name, - "file_dep": [jpy_ex_file], - "targets": [out_name], - "actions": [(utils.copy_file, [jpy_ex_file, out_name])], - "clean": True, - } - - jupyter_headers[ex_category]["files"] = natsort.natsorted( - jupyter_headers[ex_category]["files"], alg=natsort.IC - ) - - out_name = kw["output_folder"].joinpath(self.examples_folder, kw["index_file"]) - yield { - "basename": self.name, - "name": str(out_name), - "file_dep": index_template_deps + list(map(str, jupyter_examples)), - "targets": [out_name], - "actions": [ - (render_example_index, [self.site, kw, jupyter_headers, out_name]) - ], - # This is necessary to reflect changes in blog title, - # sidebar links, etc. - "uptodate": [utils.config_changed(uptodate, "jupyter_examples:folder")], - "clean": True, - } diff --git a/plugins/render_matlab_examples.plugin b/plugins/render_matlab_examples.plugin deleted file mode 100644 index 4fa578dc1..000000000 --- a/plugins/render_matlab_examples.plugin +++ /dev/null @@ -1,8 +0,0 @@ -[Core] -Name = render_matlab_examples -Module = render_matlab_examples - -[Documentation] -Author = Bryan Weber -Version = 0.1 -Description = Build the Cantera Matlab examples into the output diff --git a/plugins/render_matlab_examples.py b/plugins/render_matlab_examples.py deleted file mode 100644 index 80833477b..000000000 --- a/plugins/render_matlab_examples.py +++ /dev/null @@ -1,232 +0,0 @@ -"""Render the Matlab examples from the Cantera repository into Nikola listings. - -This plugin renders Matlab examples from the main Cantera repository into the -examples/matlab output folder. It looks for the examples in the folder configured -in the top-level conf.py file in the ``EXAMPLES_FOLDERS`` dictionary. That -dictionary has keys with the source folder and values with the destination -folder (relative to the ``OUTPUT_FOLDER``). The relevant source folder is found -as the key associated with the value that contains the string ``matlab``, -typically ``"../cantera/samples/matlab": "examples/matlab"``. -""" -from pathlib import Path - -from nikola.plugin_categories import Task -from nikola import utils -from pygments import highlight -from pygments.lexers import MatlabLexer -import natsort - - -def render_example_index(site, kw, headers, output_file): - """Render the index of all of the Matlab examples. - - Parameters - ========== - site: - An instance of a Nikola site, available in any plugin as ``self.site`` - kw: - A dictionary of keywords for this task - headers: - A dictionary of the example categories and the summaries of each example - output_file: - A pathlib.Path instance representing the output file that will be rendered - - """ - n = 3 - for head_dict in headers.values(): - head_files = head_dict["files"] - head_dict["files"] = [ - head_files[i : i + n] for i in range(0, len(head_files), n) # NOQA: E203 - ] - - permalink = output_file.relative_to(kw["output_folder"]) - title = "Matlab Examples" - context = { - "headers": headers, - "lang": kw["default_lang"], - "pagekind": ["example"], - "permalink": str(permalink), - "title": title, - "description": title, - } - site.render_template("matlab-example-index.tmpl", str(output_file), context) - - -def render_example(site, kw, in_name, out_name): - """Render a single .m file to HTML with formatting. - - Parameters - ========== - site: - An instance of a Nikola site, available in any plugin as ``self.site`` - kw: - A dictionary of keywords for this task - in_name: - The file to be rendered, as an instance of pathlib.Path - out_name: - A pathlib.Path instance pointing to the rendered output file - - """ - code = highlight( - in_name.read_bytes(), MatlabLexer(), utils.NikolaPygmentsHTML(in_name.name) - ) - - title = in_name.name - permalink = out_name.relative_to(kw["output_folder"]) - source_link = permalink.stem # remove '.html' - context = { - "code": code, - "title": title, - "permalink": str(permalink), - "lang": kw["default_lang"], - "description": title, - "source_link": source_link, - "pagekind": ["example"], - } - site.render_template("examples.tmpl", str(out_name), context) - - -class RenderMatlabExamples(Task): - """Render the Matlab examples with a Nikola Task. - - As with all Nikola ``Tasks``, the key method here is the ``gen_tasks`` - method, which yields dictionaries that represent tasks that doit needs - to run. There are two primary kinds of tasks, one that renders each - example file, and one that renders an index of all of the examples. - """ - - name = "render_matlab_examples" - - def set_site(self, site): - """Set Nikola site.""" - # Verify that a Python output folder appears only once in EXAMPLES_FOLDERS - found_matlab = False - for source, dest in site.config["EXAMPLES_FOLDERS"].items(): - if "matlab" in dest: - if found_matlab: - self.logger.error( - "More than one folder to output Matlab examples was found in " - "EXAMPLES_FOLDERS, exiting" - ) - else: - found_matlab = True - self.input_folder = source - self.examples_folder = dest - - if not found_matlab: - self.logger.warn( - "Didn't find an output folder for Matlab examples in EXAMPLES_FOLDERS" - ) - - return super().set_site(site) - - def gen_tasks(self): - """Render examples.""" - kw = { - "default_lang": self.site.config["DEFAULT_LANG"], - "examples_folders": self.site.config["EXAMPLES_FOLDERS"], - "output_folder": Path(self.site.config["OUTPUT_FOLDER"]), - "index_file": self.site.config["INDEX_FILE"], - "strip_indexes": self.site.config["STRIP_INDEXES"], - } - - yield self.group_task() - - # When any key or value in the uptodate dictionary changes, the - # examples pages need to be rebuilt. - uptodate = {"c": self.site.GLOBAL_CONTEXT} - - for k, v in self.site.GLOBAL_CONTEXT["template_hooks"].items(): - uptodate["||template_hooks|{0}||".format(k)] = v.calculate_deps() - - for k in self.site._GLOBAL_CONTEXT_TRANSLATABLE: - uptodate[k] = self.site.GLOBAL_CONTEXT[k](kw["default_lang"]) - - # save navigation links as dependencies - uptodate["nav_links"] = uptodate["c"]["navigation_links"](kw["default_lang"]) - - uptodate["kw"] = kw - - examples_template_deps = self.site.template_system.template_deps( - "examples.tmpl" - ) - - index_template_deps = self.site.template_system.template_deps( - "matlab-example-index.tmpl" - ) - matlab_examples = list(Path(self.input_folder).resolve().glob("*.m")) - matlab_headers = { - "examples": {"name": "Examples", "files": [], "summaries": {}} - } - - uptodate["d"] = matlab_headers.keys() - uptodate["f"] = list(map(str, matlab_examples)) - - for mat_ex_file in matlab_examples: - if "tut" in mat_ex_file.name or "test" in mat_ex_file.name: - continue - matlab_headers["examples"]["files"].append(mat_ex_file) - doc = "" - for line in mat_ex_file.read_text(encoding="utf-8").split("\n"): - line = line.strip() - if line.startswith("%"): - doc = line.strip("%").strip() - if doc: - break - if not doc: - self.logger.warn( - "The Matlab example {!s} doesn't have an appropriate summary. The " - "first comment line of the Matlab file is taken as the " - "summary.".format(mat_ex_file) - ) - name = mat_ex_file.stem.replace("_", " ") - if doc.lower().replace("_", " ").startswith(name): - doc = doc[len(name) :].lstrip("- ") # NOQA: E203 - matlab_headers["examples"]["summaries"][mat_ex_file.name] = doc - - out_name = kw["output_folder"].joinpath( - self.examples_folder, mat_ex_file.with_suffix(".m.html").name - ) - - yield { - "basename": self.name, - "name": str(out_name), - "file_dep": examples_template_deps + [mat_ex_file], - "targets": [out_name], - "actions": [(render_example, [self.site, kw, mat_ex_file, out_name])], - # This is necessary to reflect changes in blog title, - # sidebar links, etc. - "uptodate": [utils.config_changed(uptodate, "matlab_examples:source")], - "clean": True, - } - - out_name = kw["output_folder"].joinpath( - self.examples_folder, mat_ex_file.name - ) - yield { - "basename": self.name, - "name": str(out_name), - "file_dep": [mat_ex_file], - "targets": [out_name], - "actions": [(utils.copy_file, [mat_ex_file, out_name])], - "clean": True, - } - - matlab_headers["examples"]["files"] = natsort.natsorted( - matlab_headers["examples"]["files"], alg=natsort.IC - ) - - out_name = kw["output_folder"].joinpath(self.examples_folder, kw["index_file"]) - yield { - "basename": self.name, - "name": str(out_name), - "file_dep": index_template_deps + list(map(str, matlab_examples)), - "targets": [out_name], - "actions": [ - (render_example_index, [self.site, kw, matlab_headers, out_name]) - ], - # This is necessary to reflect changes in blog title, - # sidebar links, etc. - "uptodate": [utils.config_changed(uptodate, "matlab_examples:folder")], - "clean": True, - } diff --git a/plugins/render_python_examples.plugin b/plugins/render_python_examples.plugin deleted file mode 100644 index 437659ba2..000000000 --- a/plugins/render_python_examples.plugin +++ /dev/null @@ -1,8 +0,0 @@ -[Core] -Name = render_python_examples -Module = render_python_examples - -[Documentation] -Author = Bryan Weber -Version = 0.1 -Description = Render the Cantera Python examples into the output diff --git a/plugins/render_python_examples.py b/plugins/render_python_examples.py deleted file mode 100644 index 0e641292e..000000000 --- a/plugins/render_python_examples.py +++ /dev/null @@ -1,242 +0,0 @@ -"""Render the Python examples from the Cantera repository into Nikola listings. - -This plugin renders Python examples from the main Cantera repository into the -examples/matlab output folder. It looks for the examples in the folder configured -in the top-level conf.py file in the ``EXAMPLES_FOLDERS`` dictionary. That -dictionary has keys with the source folder and values with the destination -folder (relative to the ``OUTPUT_FOLDER``). The relevant source folder is found -as the key associated with the value that contains the string ``python``, -typically ``"../cantera/samples/python": "examples/python"``. -""" -from pathlib import Path -import ast -from collections import OrderedDict - -from nikola.plugin_categories import Task -from nikola import utils -import natsort -from pygments import highlight -from pygments.lexers import Python3Lexer - - -def render_example_index(site, kw, headers, output_file): - """Render the index of all of the Python examples. - - Parameters - ========== - site: - An instance of a Nikola site, available in any plugin as ``self.site`` - kw: - A dictionary of keywords for this task - headers: - A dictionary of the example categories and the summaries of each example - output_file: - A pathlib.Path instance representing the output file that will be rendered - - """ - n = 3 - for head_dict in headers.values(): - head_files = head_dict["files"] - head_dict["files"] = [ - head_files[i : i + n] for i in range(0, len(head_files), n) # NOQA: E203 - ] - - permalink = output_file.relative_to(kw["output_folder"]) - title = "Python Examples" - context = { - "headers": headers, - "lang": kw["default_lang"], - "pagekind": ["example"], - "permalink": str(permalink), - "title": title, - "description": title, - } - site.render_template("python-example-index.tmpl", str(output_file), context) - - -def render_example(site, kw, in_name, out_name): - """Render a single .py file to HTML with formatting. - - Parameters - ========== - site: - An instance of a Nikola site, available in any plugin as ``self.site`` - kw: - A dictionary of keywords for this task - in_name: - The file to be rendered, as an instance of pathlib.Path - out_name: - A pathlib.Path instance pointing to the rendered output file - - """ - code = highlight( - in_name.read_bytes(), Python3Lexer(), utils.NikolaPygmentsHTML(in_name.name) - ) - - title = in_name.name - - permalink = out_name.relative_to(kw["output_folder"]) - source_link = permalink.stem # remove '.html' - context = { - "code": code, - "title": title, - "permalink": str(permalink), - "lang": kw["default_lang"], - "description": title, - "source_link": source_link, - "pagekind": ["example"], - } - site.render_template("examples.tmpl", str(out_name), context) - - -class RenderPythonExamples(Task): - """Render the Python examples with a Nikola Task. - - As with all Nikola ``Tasks``, the key method here is the ``gen_tasks`` - method, which yields dictionaries that represent tasks that doit needs - to run. There are two primary kinds of tasks, one that renders each - example file, and one that renders an index of all of the examples. - """ - - name = "render_python_examples" - - def set_site(self, site): - """Set Nikola site.""" - # Verify that a Python output folder appears only once in EXAMPLES_FOLDERS - found_python = False - for source, dest in site.config["EXAMPLES_FOLDERS"].items(): - if "python" in dest: - if found_python: - self.logger.error( - "More than one folder to output Python examples was found in " - "EXAMPLES_FOLDERS, exiting" - ) - else: - found_python = True - self.input_folder = source - self.examples_folder = dest - - if not found_python: - self.logger.warn( - "Didn't find an output folder for Python examples in EXAMPLES_FOLDERS" - ) - - return super().set_site(site) - - def gen_tasks(self): - """Render examples.""" - kw = { - "default_lang": self.site.config["DEFAULT_LANG"], - "examples_folders": self.site.config["EXAMPLES_FOLDERS"], - "output_folder": Path(self.site.config["OUTPUT_FOLDER"]), - "index_file": self.site.config["INDEX_FILE"], - "strip_indexes": self.site.config["STRIP_INDEXES"], - } - - yield self.group_task() - - # When any key or value in the uptodate dictionary changes, the - # examples pages need to be rebuilt. - uptodate = {"c": self.site.GLOBAL_CONTEXT} - - for k, v in self.site.GLOBAL_CONTEXT["template_hooks"].items(): - uptodate["||template_hooks|{0}||".format(k)] = v.calculate_deps() - - for k in self.site._GLOBAL_CONTEXT_TRANSLATABLE: - uptodate[k] = self.site.GLOBAL_CONTEXT[k](kw["default_lang"]) - - # save navigation links as dependencies - uptodate["nav_links"] = uptodate["c"]["navigation_links"](kw["default_lang"]) - - uptodate["kw"] = kw - - examples_template_deps = self.site.template_system.template_deps( - "examples.tmpl" - ) - - index_template_deps = self.site.template_system.template_deps( - "python-example-index.tmpl" - ) - python_headers = OrderedDict( - thermo=dict(files=[], summaries={}, name="Thermodynamics"), - kinetics=dict(files=[], summaries={}, name="Kinetics"), - transport=dict(files=[], summaries={}, name="Transport"), - reactors=dict(files=[], summaries={}, name="Reactor Networks"), - onedim=dict(files=[], summaries={}, name="One-Dimensional Flames"), - multiphase=dict(files=[], summaries={}, name="Multiphase Mixtures"), - surface_chemistry=dict(files=[], summaries={}, name="Surface Chemistry"), - ) - - python_examples = list(Path(self.input_folder).resolve().glob("*/*.py")) - uptodate["d"] = python_headers.keys() - uptodate["f"] = list(map(str, python_examples)) - - for py_ex_file in python_examples: - ex_category = py_ex_file.parent.stem - - if not python_headers.get(ex_category, False): - self.logger.warn( - "The category {} in the Python examples has no header. " - "Please add the folder to the python_headers dictionary in the " - "render_python_examples plugin".format(ex_category) - ) - continue - - python_headers[ex_category]["files"].append(py_ex_file) - mod = ast.parse(py_ex_file.read_bytes()) - for node in mod.body: - if isinstance(node, ast.Expr) and isinstance(node.value, ast.Str): - doc = node.value.s.strip().split("\n\n")[0].strip() - if not doc.endswith("."): - doc += "." - break - python_headers[ex_category]["summaries"][py_ex_file.name] = doc - - out_name = kw["output_folder"].joinpath( - self.examples_folder, - ex_category, - py_ex_file.with_suffix(".py.html").name, - ) - yield { - "basename": self.name, - "name": str(out_name), - "file_dep": examples_template_deps + [py_ex_file], - "targets": [out_name], - "actions": [(render_example, [self.site, kw, py_ex_file, out_name])], - # This is necessary to reflect changes in blog title, - # sidebar links, etc. - "uptodate": [utils.config_changed(uptodate, "python_examples:source")], - "clean": True, - } - - out_name = kw["output_folder"].joinpath( - self.examples_folder, ex_category, py_ex_file.name - ) - yield { - "basename": self.name, - "name": out_name, - "file_dep": [py_ex_file], - "targets": [out_name], - "actions": [(utils.copy_file, [py_ex_file, out_name])], - "clean": True, - } - - for head in python_headers.keys(): - python_headers[head]["files"] = natsort.natsorted( - python_headers[head]["files"], alg=natsort.IC - ) - - out_name = kw["output_folder"].joinpath(self.examples_folder, kw["index_file"]) - yield { - "basename": self.name, - "name": str(out_name), - "file_dep": index_template_deps + list(map(str, python_examples)), - "targets": [out_name], - "actions": [ - (render_example_index, [self.site, kw, python_headers, out_name]) - ], - # This is necessary to reflect changes in blog title, - # sidebar links, etc. - "uptodate": [utils.config_changed(uptodate, "python_examples:folder")], - "clean": True, - } diff --git a/plugins/rest_class.py b/plugins/rest_class.py deleted file mode 100644 index 58985c6f8..000000000 --- a/plugins/rest_class.py +++ /dev/null @@ -1,130 +0,0 @@ -"""Parser for :class: and :func: roles. - -This module implements a reST extension to put links for the ``:class:`` -and ``:func:`` roles based on links to the documentation. The links -are stored in the site cache in the ``*_targets`` key, where the ``*`` -is one of the contexts, ``py``, ``mat``, and ``cti``. The targets are -generated and stored in the cache by the ``parse_docs`` plugin. -""" - -from docutils import nodes -from docutils.parsers.rst import roles - -from nikola.utils import split_explicit_title, get_logger -from nikola.plugin_categories import RestExtension - - -LOGGER = get_logger("rest_class") - - -class Plugin(RestExtension): - """Plugin for :class: and :func: role.""" - - name = "rest_class" - - def set_site(self, site): - """Set the Nikola site instance for this plugin.""" - self.site = site - roles.register_canonical_role("class", class_role) - roles.register_canonical_role("cti:class", class_role) - roles.register_canonical_role("py:class", class_role) - roles.register_canonical_role("mat:class", class_role) - roles.register_canonical_role("func", class_role) - roles.register_canonical_role("cti:func", class_role) - roles.register_canonical_role("py:func", class_role) - roles.register_canonical_role("mat:func", class_role) - class_role.site = site - return super(Plugin, self).set_site(site) - - -def _class_link(name, rawtext, text): - """Handle the class role.""" - if class_role.site.processing_targets: - return True, True, None, None, None, None - - context_map = {"py": "cython", "mat": "matlab", "cti": "cti"} - context = name.split(":", 1)[0] - if context == name: - context = class_role.site.config["DEFAULT_CONTEXT"] - default_context = True - else: - default_context = False - - target = "{}_targets".format(context_map[context]) - - if class_role.site.cache.get(target) is not None: - targets = class_role.site.cache.get(target).copy() - else: - targets = getattr(class_role.site, target).copy() - - has_explicit_title, title, label = split_explicit_title(text) - - if label not in targets and not default_context: - LOGGER.error( - "The label {label} was not found in the context {context}".format( - label=label, context=context - ) - ) - return False, False, None, None, None, label - elif label not in targets and default_context: - c_map = context_map.copy() - c_map.pop(context) - found_label = False - for context, t in c_map.items(): - target = "{}_targets".format(t) - if class_role.site.cache.get(target) is not None: - targets = class_role.site.cache.get(target).copy() - else: - targets = getattr(class_role.site, target).copy() - - if label not in targets: - continue - else: - found_label = True - LOGGER.info( - "The label {} was found in the context {}. Consider explicitly " - "specifying the context for this link".format(label, context) - ) - break - - if not found_label: - LOGGER.error("The label {} could not be found in any context".format(label)) - return False, False, None, None, None, label - - doc_file = targets[label][0] - permalink = "/documentation/docs-{}/".format( - class_role.site.config["CANTERA_VERSION"] - ) - permalink += doc_file + "#" + targets[label][1] - code_node = nodes.literal( - rawtext, targets[label][2] + "()", classes=["code", "xref", context] - ) - if not has_explicit_title: - title = targets[label][1] - - return True, False, title, code_node, permalink, label - - -def class_role(name, rawtext, text, lineno, inliner, options={}, content=[]): - """Handle the class role.""" - success, processing, title, code_node, permalink, label = _class_link( - name, rawtext, text - ) - if processing: - return [nodes.raw("", text, format="html")], [] - if success: - node = make_link_node(rawtext, title, code_node, permalink, options) - return [node], [] - else: - msg = inliner.reporter.warning( - "The label {0} was not found".format(label), line=lineno - ) - prb = inliner.problematic(rawtext, rawtext, msg) - return [prb], [msg] - - -def make_link_node(rawtext, text, code_node, url, options): - """Make a docutils link node.""" - node = nodes.reference("", "", refuri=url, *options) - node.append(code_node) - return node diff --git a/posts/GSoC_2019_Third_Blog.md b/posts/GSoC_2019_Third_Blog.md deleted file mode 100644 index 113300919..000000000 --- a/posts/GSoC_2019_Third_Blog.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: GSoC 2019 Third Blog -date: 2019-07-06 13:59 UTC-17:59 -slug: GSoC_2019_Third_Blog -tags: GSoC 2019 -description: 2019 Google Summer of Code Cantera Project Blog -type: text -author: Chao Xu ---- - -# GSoC Third Blog -- Function update - -As we planned after the first evaluation, the functionality of ChemCheck should be more robust. File replacement was added, and users are able to -update and delete files arbitrarily. - -<!-- TEASER_END --> - -The page looks like this: - -{{% thumbnail "/images/GSoC_2019_images/detail_page2.png" alt="Updated Detail Page" align="center" %}}<p class="text-center">Updated Detail Page</p>{{% /thumbnail %}} - -The delete button leads to a delete page, which will delete files in both the database and the directory. - -{{% thumbnail "/images/GSoC_2019_images/delete_page.png" alt="Delete Page" align="center" %}}<p class="text-center">Delete Page</p>{{% /thumbnail %}} - -In the update page, users can either replace their files or delete it by checking "clear". - -{{% thumbnail "/images/GSoC_2019_images/update_page.png" alt="Update Page" align="center" %}}<p class="text-center">Update Page</p>{{% /thumbnail %}} - -In addition to these, new features ChemCheck can provide the traceback message instead of only one line error. - -{{% thumbnail "/images/GSoC_2019_images/error_page.png" alt="Error Page" align="center" %}}<p class="text-center">Error Page</p>{{% /thumbnail %}} - -An editing function is also included: - -{{% thumbnail "/images/GSoC_2019_images/ace_editor.png" alt="Editor Page" align="center" %}}<p class="text-center">Editor Page</p>{{% /thumbnail %}} - -## Next Steps - -I am working toward catching logging messages to make the error understandable and making the error page look nicer. Also, I will improve editing function (adding download function in editor page, and change highlight settings of ace editor). After that, I will test different -defective mechanism files and providing fix suggestions. diff --git a/posts/new-website-is-live.md b/posts/new-website-is-live.md deleted file mode 100644 index 5670434df..000000000 --- a/posts/new-website-is-live.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: New website is live! -date: 2018-07-02 15:02:00 UTC -slug: new-website-is-live -tags: website -description: The new Cantera website is here! -type: text -author: Bryan Weber ---- - -# The New Cantera Website is Here! - -This summer, Bryan Weber and Steven DeCaluwe took on the project of revamping the Cantera website. -The old website was, well, old and needed to be refreshed. Thanks to a grant from -[NumFOCUS][numfocus], Bryan and Steven were able to completely redo the website! - -<!-- TEASER_END --> - -The main focus of the update was to make it much easier for all users of Cantera to quickly find the -information they need. The older website was a list of links to locations deeper in the website, -which made it hard for new and expert users of Cantera to find the page they were looking for. On -the new website, we have clearly marked sections for new users and advanced users to find what -they're looking for. All of the same content is available, we've just reorganized it and -(hopefully!) made things easier to find. - -{{% thumbnail "/images/new-website-is-live/old-cantera-website.png" alt="Old Cantera Website" align="center" %}}<p class="text-center">Old Cantera Website</p>{{% /thumbnail %}} - -We have a [Tutorials section][tutorials] to get new users started with using Cantera, we have a -separate ["Science" section][science] that explains some of the basic equations and principles -underlying the models that Cantera uses, and we still have all the API documentation that you need -over in the [Documentation section][docs]. There is also a [Community section][community] with -information about how to reach the Cantera steering community and where our code and discussions -live. - -## NumFOCUS - -This work was sponsored by NumFOCUS through their Small Development Grants program. This program -gives small grants to NumFOCUS sponsored projects to help improve their code or their community. -Cantera was awarded the grant as part of the [Spring 2018 round of funding][nf-blog-post]. If you -are interested in more information about this grant, or future grants, please email the [steering -committee][steering-committee]. More information about [NumFOCUS][numfocus] can be found in the -[Community section][donate] of our new website! Thank you NumFOCUS! - -## Nuts and bolts - -The website is now built with the Nikola static site generator and much of the content has been -migrated to a [new repository][website-repo]. The allows us to update the website content without -pushing commits to the main Cantera repository and rebuilding all of the documentation. The website -is themed with the [Bootstrap 4][bootstrap] theme. The documentation of the Cantera API is still -done with Sphinx and Doxygen in the [main code repository][main-repo]. - -All of the links to the old website structure should be automatically redirected to the equivalent -location in the new structure. If you find any redirects that don't work, or any broken links within -cantera.org, please [file an issue][file] on our website repository. - -There are still a few things we're working out with the new site. If you would like to contribute, -check out the [issues page][issues] on our repository and leave a comment! - -[website-repo]: https://github.com/Cantera/cantera-website -[issues]: https://github.com/Cantera/cantera-website/issues -[tutorials]: https://cantera.org/tutorials/index.html -[science]: https://cantera.org/science/index.html -[docs]: https://cantera.org/documentation/index.html -[community]: https://cantera.org/community.html -[bootstrap]: https://getbootstrap.com -[nf-blog-post]:https://www.numfocus.org/blog/numfocus-awards-development-grants-to-open-source-projects-spring-2018 -[numfocus]: https://numfocus.org -[donate]: https://cantera.org/community.html#supporting-cantera -[file]: https://github.com/Cantera/cantera-website/issues/new -[main-repo]: https://github.com/Cantera/cantera -[steering-committee]: mailto:steering@cantera.org diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 000000000..af50a5037 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,44 @@ +[project] +name = "cantera-website" +version = "3.1" +description = "" +authors = [{ name = "Cantera Developers", email = "developers@cantera.org" }] +dependencies = [ + "sphinx>=6.2.1", + "pydata-sphinx-theme==0.15.2", + "myst-parser>=2.0.0", + "sphinx-design>=0.4.1", + "sphinx-autobuild>=2021.3.14", + "ablog>=0.11.6", + "sphinxcontrib.mermaid", +] +requires-python = ">=3.10" +license = { text = "BSD-3-Clause" } + +[tool.pdm] +package-type = "application" + +[tool.pdm.dev-dependencies] +lint = ["pre-commit>=3.3.3"] + +[tool.pdm.scripts] +build = { cmd = [ + "sphinx-build", + "-b", + "html", + "-W", + "--keep-going", + "source", + "build/html", + "-a", +] } +rebuild = { cmd = [ + "sphinx-autobuild", + "source", + "build/html", + "--watch", + "source", + "--port", + "0", + "--open-browser", +] } diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index de5914489..000000000 --- a/requirements.txt +++ /dev/null @@ -1,15 +0,0 @@ -Nikola[extras]==8.2.1 -yapsy==1.11.* -attrs>=17.4.0 -Markdown==3.3.7 -pymdown-extensions==5.0 -GitPython>=3.0.5,<4.0 -Pygments>=2.7.0 -nbconvert==6.4.3 -nbformat>=5.2.0 -# Pin until the bootstrap.py plugin here can be updated. -# Something with docutils==0.17 broke that plugin -docutils==0.16 -# Pin until nbconvert is updated to suport jinja2>=3.1.0 -jinja2>=3.0.3,<3.1.0 -scons>=3.0.0 diff --git a/shortcodes/ct_dev_docs.tmpl b/shortcodes/ct_dev_docs.tmpl deleted file mode 100644 index f3508f81d..000000000 --- a/shortcodes/ct_dev_docs.tmpl +++ /dev/null @@ -1 +0,0 @@ -{{ '/' if site.config['BASE_URL'] == site.config['SITE_URL'] else site.config['BASE_URL'] }}dev/{{ _args[0] if _args else link }} diff --git a/shortcodes/ct_docs.tmpl b/shortcodes/ct_docs.tmpl deleted file mode 100644 index ce8d72be0..000000000 --- a/shortcodes/ct_docs.tmpl +++ /dev/null @@ -1 +0,0 @@ -{{ '/' if site.config['BASE_URL'] == site.config['SITE_URL'] else site.config['BASE_URL'] }}documentation/docs-{{ site.config['CANTERA_VERSION'] }}/{{ _args[0] if _args else link }} diff --git a/pages/403.html b/source/403.html similarity index 100% rename from pages/403.html rename to source/403.html diff --git a/pages/404.html b/source/404.html similarity index 100% rename from pages/404.html rename to source/404.html diff --git a/pages/500.html b/source/500.html similarity index 100% rename from pages/500.html rename to source/500.html diff --git a/pages/503.html b/source/503.html similarity index 100% rename from pages/503.html rename to source/503.html diff --git a/source/_static/css/custom.css b/source/_static/css/custom.css new file mode 100644 index 000000000..cf598fb50 --- /dev/null +++ b/source/_static/css/custom.css @@ -0,0 +1,110 @@ +html { + --pst-icon-external-link: ""; +} + +p + div.math { + /* Remove post-paragraph space ahead of equation to center vertically */ + margin-top: -1.15em; +} + +.bd-header .navbar-header-items__center, .bd-header .navbar-header-items__end { + /* Remove space between manually-inserted header items and Sphinx-generated ones */ + column-gap: 0; +} + +/* Make extra room for header section links when page isn't wide enough */ +@media(max-width: 1199.88px) { + /* Collapse search field to just a button */ + button.search-button-field .search-button__default-text { + display: none; + visibility: hidden; + } + .search-button-field > :not(svg) { + display: none; + visibility: hidden; + } + + /* Hide text portion of the Cantera logo */ + .navbar-brand img { + width: 36px; + object-fit: cover; + object-position: left + } +} + +.mermaid { + text-align: center; + } + +.theme-switch-button span { + padding: 1.6em; +} + +/* Make "tip" background color different from "versionadded" */ +.admonition.tip, +div.admonition.tip { + border-color:var(--pst-color-info) +} +.admonition.tip>.admonition-title:before, +div.admonition.tip>.admonition-title:before { + background-color:var(--pst-color-info-bg); +} +.admonition.tip>.admonition-title:after, +div.admonition.tip>.admonition-title:after { + color:var(--pst-color-info); + content:var(--pst-icon-admonition-tip) +} + +#logo { width: 250px; } +#cards { padding-bottom: 5%; } +.jumbotron-text { text-align: center; padding-bottom: 16px; font-size: 1.5rem; font-weight: 500; } +.jumbotron { background-color: white; margin-top: 30px; margin-bottom: 48px; padding: 0 0; } +.img-container { text-align: center; } + +a.headerlink { visibility: hidden; padding: 0 4px 0 4px; } +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink { + visibility: visible; +} + +.example-header { padding: 20px 0; } +.example-row { padding-bottom: 20px; } + +.tutorials { margin: 40px 0; padding: 0 0 !important; } + +section { margin-top: 20px; margin-bottom: 20px; padding: 0 0; } + +a.docs:hover { background-color: #007994; color: #ffffff; } +a.docs, a.dev-docs, a.release-notes { color: #000000; } +a.dev-docs:hover { background-color: #fd7f03; color: #ffffff; } +a.release-notes:hover { background-color: #c80202; color: #ffffff; } + +.row { margin: 0 0 20px; } + +a > tt { + color: inherit; +} + +.section-card { + font-size: 1.25rem; + font-weight: 500; +} + +.footer li { + display: inline-block; + text-decoration: none; +} +.footer li::after { + content: " |"; +} +.footer li:last-of-type::after { + content: ""; +} +.footer-text { + margin-left: 0; + padding-left: 0; +} diff --git a/images/GSoC_2019_images/ace_editor.png b/source/_static/images/GSoC_2019_images/ace_editor.png similarity index 100% rename from images/GSoC_2019_images/ace_editor.png rename to source/_static/images/GSoC_2019_images/ace_editor.png diff --git a/images/GSoC_2019_images/convert_fail.png b/source/_static/images/GSoC_2019_images/convert_fail.png similarity index 100% rename from images/GSoC_2019_images/convert_fail.png rename to source/_static/images/GSoC_2019_images/convert_fail.png diff --git a/images/GSoC_2019_images/convert_fail_page.png b/source/_static/images/GSoC_2019_images/convert_fail_page.png similarity index 100% rename from images/GSoC_2019_images/convert_fail_page.png rename to source/_static/images/GSoC_2019_images/convert_fail_page.png diff --git a/images/GSoC_2019_images/convert_success.png b/source/_static/images/GSoC_2019_images/convert_success.png similarity index 100% rename from images/GSoC_2019_images/convert_success.png rename to source/_static/images/GSoC_2019_images/convert_success.png diff --git a/images/GSoC_2019_images/delete_page.png b/source/_static/images/GSoC_2019_images/delete_page.png similarity index 100% rename from images/GSoC_2019_images/delete_page.png rename to source/_static/images/GSoC_2019_images/delete_page.png diff --git a/images/GSoC_2019_images/detail_page.png b/source/_static/images/GSoC_2019_images/detail_page.png similarity index 100% rename from images/GSoC_2019_images/detail_page.png rename to source/_static/images/GSoC_2019_images/detail_page.png diff --git a/images/GSoC_2019_images/detail_page2.png b/source/_static/images/GSoC_2019_images/detail_page2.png similarity index 100% rename from images/GSoC_2019_images/detail_page2.png rename to source/_static/images/GSoC_2019_images/detail_page2.png diff --git a/images/GSoC_2019_images/error_page.png b/source/_static/images/GSoC_2019_images/error_page.png similarity index 100% rename from images/GSoC_2019_images/error_page.png rename to source/_static/images/GSoC_2019_images/error_page.png diff --git a/images/GSoC_2019_images/list_page.png b/source/_static/images/GSoC_2019_images/list_page.png similarity index 100% rename from images/GSoC_2019_images/list_page.png rename to source/_static/images/GSoC_2019_images/list_page.png diff --git a/images/GSoC_2019_images/login.png b/source/_static/images/GSoC_2019_images/login.png similarity index 100% rename from images/GSoC_2019_images/login.png rename to source/_static/images/GSoC_2019_images/login.png diff --git a/images/GSoC_2019_images/password_change.png b/source/_static/images/GSoC_2019_images/password_change.png similarity index 100% rename from images/GSoC_2019_images/password_change.png rename to source/_static/images/GSoC_2019_images/password_change.png diff --git a/images/GSoC_2019_images/signup.png b/source/_static/images/GSoC_2019_images/signup.png similarity index 100% rename from images/GSoC_2019_images/signup.png rename to source/_static/images/GSoC_2019_images/signup.png diff --git a/images/GSoC_2019_images/update_page.png b/source/_static/images/GSoC_2019_images/update_page.png similarity index 100% rename from images/GSoC_2019_images/update_page.png rename to source/_static/images/GSoC_2019_images/update_page.png diff --git a/images/GSoC_2019_images/updated_editor.png b/source/_static/images/GSoC_2019_images/updated_editor.png similarity index 100% rename from images/GSoC_2019_images/updated_editor.png rename to source/_static/images/GSoC_2019_images/updated_editor.png diff --git a/images/GSoC_2019_images/upload_page.png b/source/_static/images/GSoC_2019_images/upload_page.png similarity index 100% rename from images/GSoC_2019_images/upload_page.png rename to source/_static/images/GSoC_2019_images/upload_page.png diff --git a/images/dave-goodwin.jpg b/source/_static/images/dave-goodwin.jpg similarity index 100% rename from images/dave-goodwin.jpg rename to source/_static/images/dave-goodwin.jpg diff --git a/images/gsoc-2020/sol-vector.png b/source/_static/images/gsoc-2020/sol-vector.png similarity index 100% rename from images/gsoc-2020/sol-vector.png rename to source/_static/images/gsoc-2020/sol-vector.png diff --git a/images/gsoc-2020/steady-state-eqs.png b/source/_static/images/gsoc-2020/steady-state-eqs.png similarity index 100% rename from images/gsoc-2020/steady-state-eqs.png rename to source/_static/images/gsoc-2020/steady-state-eqs.png diff --git a/images/gsoc-2020/v0-2-results.png b/source/_static/images/gsoc-2020/v0-2-results.png similarity index 100% rename from images/gsoc-2020/v0-2-results.png rename to source/_static/images/gsoc-2020/v0-2-results.png diff --git a/images/new-website-is-live/old-cantera-website.png b/source/_static/images/new-website-is-live/old-cantera-website.png similarity index 100% rename from images/new-website-is-live/old-cantera-website.png rename to source/_static/images/new-website-is-live/old-cantera-website.png diff --git a/themes/cantera/assets/img/Git_Logo.png b/source/_static/img/Git_Logo.png similarity index 100% rename from themes/cantera/assets/img/Git_Logo.png rename to source/_static/img/Git_Logo.png diff --git a/themes/cantera/assets/img/Groups_Logo.png b/source/_static/img/Groups_Logo.png similarity index 100% rename from themes/cantera/assets/img/Groups_Logo.png rename to source/_static/img/Groups_Logo.png diff --git a/themes/cantera/assets/img/SponsoredProject.png b/source/_static/img/SponsoredProject.png similarity index 100% rename from themes/cantera/assets/img/SponsoredProject.png rename to source/_static/img/SponsoredProject.png diff --git a/themes/cantera/assets/img/cantera-logo.png b/source/_static/img/cantera-logo.png similarity index 100% rename from themes/cantera/assets/img/cantera-logo.png rename to source/_static/img/cantera-logo.png diff --git a/source/_static/img/favicon.png b/source/_static/img/favicon.png new file mode 100644 index 000000000..a3af328e2 Binary files /dev/null and b/source/_static/img/favicon.png differ diff --git a/themes/cantera/assets/js/copybutton.js b/source/_static/js/copybutton.js similarity index 100% rename from themes/cantera/assets/js/copybutton.js rename to source/_static/js/copybutton.js diff --git a/source/_templates/initial-sections.html b/source/_templates/initial-sections.html new file mode 100644 index 000000000..da0e63aae --- /dev/null +++ b/source/_templates/initial-sections.html @@ -0,0 +1,26 @@ +<nav class="navbar-nav"> + <ul class="bd-navbar-elements navbar-nav"> + <li class="nav-item"> + <a class="nav-link nav-internal" href="/stable/install/index.html">Install</a> + </li> + + <li class="nav-item"> + <a class="nav-link nav-internal" href="/stable/userguide/index.html">User Guide</a> + </li> + + + <li class="nav-item"> + <a class="nav-link nav-internal" href="/stable/examples/index.html">Examples</a> + </li> + + + <li class="nav-item"> + <a class="nav-link nav-internal" href="/stable/reference/index.html">Reference</a> + </li> + + <li class="nav-item"> + <a class="nav-link nav-internal" href="/stable/develop/index.html">Develop</a> + </li> + + </ul> +</nav> diff --git a/source/_templates/search-stable.html b/source/_templates/search-stable.html new file mode 100644 index 000000000..4bed2252a --- /dev/null +++ b/source/_templates/search-stable.html @@ -0,0 +1,10 @@ +{# Override path to search page so we search the stable docs, except for News pages #} +<script> + if (window.location.pathname.startsWith("/news")) { + inp = document.getElementById('search-input'); + inp.placeholder = "Search news ..."; + inp.ariaLabel = "Search news ..."; + } else { + document.getElementsByClassName('bd-search')[0].action = "/stable/search.html"; + } +</script> diff --git a/source/affiliated.md b/source/affiliated.md new file mode 100644 index 000000000..20634d83d --- /dev/null +++ b/source/affiliated.md @@ -0,0 +1,158 @@ +# Affiliated Packages + +While Cantera provides some standalone models and applications, numerous external +packages exist that provide more specialized functionality and rely on Cantera. Here we +provide a non-exhaustive, alphabetical, list of these packages; if you would like us to +include your package, please [submit a pull request](https://github.com/cantera/cantera-website/pulls), +[file an issue](https://github.com/cantera/cantera-website/issues/new), or +post on the [Google Users' Group](https://groups.google.com/g/cantera-users). + +::::{grid} 1 2 2 2 + +:::{grid-item-card} Arrhenius.jl +Differential combustion modeling software in Julia. + +[Repository](https://github.com/DENG-MIT/Arrhenius.jl) + +Maintainer(s): Weiqi Ji +::: + +:::{grid-item-card} ASALI +Graphical user interface for calculating properties using Cantera. + +[Repository](https://github.com/srebughini/ASALI) + +Maintainer(s): Stefano Rebughini +::: + +:::{grid-item-card} BIOVIA Materials Studio +Commercial modeling and simulation software for materials science and chemistry. + +[Website](https://www.3ds.com/products/biovia/materials-studio) +::: + +:::{grid-item-card} CollectionOfMechanisms +A hub for combustion reaction mechanisms including converted Cantera XML and YAML based +mechanisms. + +[Repository](https://github.com/jiweiqi/CollectionOfMechanisms) + +Maintainer(s): Weiqi Ji, Jeff Santner +::: + +:::{grid-item-card} ChemCheck +A tool to help Cantera users to detect chemical and syntax errors in kinetic models + +[Repository](https://github.com/comocheng/ChemCheck) + +Maintainer(s): Chao Xu, Richard West +::: + +:::{grid-item-card} ctwrap +A light-weight Python wrapper facilitating batch simulations. + +[Website](https://microcombustion.github.io/ctwrap/) + +[Repository](https://github.com/microcombustion/ctwrap) + +Maintainer(s): Ingmar Schoegl +::: + +:::{grid-item-card} Ember +A quasi-one-dimensional, unsteady reacting flow solver that can simulate a number of +fundamental flame configurations: premixed laminar flames, opposed-flow strained flames +(premixed or diffusion), axisymmetric (tubular) flames with positive or negative +curvature, and steady 2D flames in a prescribed velocity field. + +[Repository](https://github.com/speth/ember) + +Maintainer(s): [Ray Speth](https://github.com/speth) +::: + +:::{grid-item-card} Frhodo +A GUI-based application for simulating experimental data and optimizing chemical +kinetics mechanisms. + +[Repository](https://github.com/Argonne-National-Laboratory/Frhodo) + +Maintainer(s): Travis Sikes, Robert Tranter +::: + +:::{grid-item-card} gas-properties +A python GUI for calculating properties of gases, equilibrium states, and isentropic +compression. Similar to unsupported GasEQ software. + +[Repository](https://github.com/jsantner/gas-properties) + +Maintainer(s): Jeff Santner +::: + +:::{grid-item-card} PoKiTT +A library for Portable Kinetics, Thermodynamics, and Transport calculations. + +[Repository](https://gitlab.multiscale.utah.edu/common/PoKiTT) + +Maintainer(s): James Sutherland +::: + +:::{grid-item-card} pyJac +Generates C and CUDA source code for analytically calculating the Jacobian matrix for a +chemical kinetic model, along with species and reaction rates. + +[Website](http://slackha.github.io/pyJac/) + +[Repository](https://github.com/SLACKHA/pyJac) + +Maintainer(s): Nick Curtis, Kyle Niemeyer +::: + +:::{grid-item-card} pyMARS +Python-based (chemical kinetic) Model Automatic Reduction Software (pyMARS) implements +multiple techniques for reducing the size and complexity of detailed chemical kinetic +models. + +[Repository](https://github.com/Niemeyer-Research-Group/pyMARS) + +Maintainer(s): Phillip Mestas, Kyle Niemeyer +::: + +:::{grid-item-card} reactorch +A Differentiable Reacting Flow Simulation Package in PyTorch. + +[Repository](https://github.com/DENG-MIT/reactorch) + +Maintainer(s): Weiqi Ji +::: + +:::{grid-item-card} RGFROSH +A Python real and ideal gas frozen shock solver. + +[Website](https://VasuLab.github.io/RGFROSH) + +[Repository](https://github.com/VasuLab/RGFROSH) + +Maintainer(s): Cory Kinney +::: + +:::{grid-item-card} RMG +Reaction Mechanism Generator, a tool for automatically generating chemical reaction +mechanisms for modeling reaction systems including pyrolysis, combustion, atmospheric +science, and more. + +[Website](https://rmg.mit.edu) + +[Repository](https://github.com/ReactionMechanismGenerator/RMG-Py) + +Maintainer(s): William Green, Richard West +::: + +:::{grid-item-card} SDToolbox +The Shock & Detonation Toolbox enables the solution of standard problems for gas-phase +explosions using realistic thermochemistry and detailed chemical kinetics. + +[Website](http://shepherd.caltech.edu/EDL/PublicResources/sdt/) + +Maintainer(s): Joseph E. Shepherd +::: + +:::: diff --git a/source/community.md b/source/community.md new file mode 100644 index 000000000..2c7e20724 --- /dev/null +++ b/source/community.md @@ -0,0 +1,194 @@ +# The Cantera Community + +_Resources to help you participate in the community of Cantera users and developers_ + +## About the Cantera Community + +Cantera was originally developed by {doc}`Prof. David G. Goodwin <dave-goodwin>` at the +California Institute of Technology. Building on Prof. Goodwin's legacy, Cantera is +licensed under a [permissive 3-Clause BSD license](https://github.com/Cantera/cantera/blob/main/License.txt), +ensuring that the software will remain open source and available for all to use. + +In this vein, Cantera software relies exclusively upon the volunteer contributions of +its users. These contributions range from diagnosing and reporting problems/bugs, to +helping others learn to use Cantera, to developing and implementing new software +capabilities. + +While Cantera provides some standalone models and applications, numerous external +packages exist that provide more specialized functionality and rely on Cantera. We +provide a non-exhaustive list of these {doc}`affiliated packages <affiliated>`. + +### Governance + +Cantera is governed by a Steering Committee; more information about our project's +governance policies can be found on the {doc}`governance <governance>` page. + +### The Cantera Users' Group + +The [Cantera Users’ Group](https://groups.google.com/g/cantera-users) on Google Groups +is the forum where most Cantera users have their questions asked and answered. If you +need help using Cantera and cannot find an answer in the tutorials or documentation at +Cantera's website, consider joining and asking a question there. A few notes: + +- Please use the search feature before posting to see if your question has been answered + before. +- If you are not running the current stable release of Cantera, please upgrade first, + and see if the problem persists. +- This group is moderated, so it may take some time for your posts to appear if you are + a new member. + +For installation/compilation problems, please provide: + +- The contents of the `cantera.conf` and `config.log` files, and the output of the + `scons build` and `scons build dump` commands. You can direct this output to a file + called `buildlog.txt` by running: + + ``` + scons build >buildlog.txt 2>&1 + ``` + +- The exact version of Cantera you are trying to compile, and how it was + obtained (for example, downloaded source tarball or the specific Git commit). + +- Your operating system, compiler versions, and the versions of any other relevant + software. + +For application problems (that is, not related to installation or compilation), please: + +- Provide a minimal, complete, and verifiable example that demonstrates the problem when + making your post; in short this means include a code example and input files. +- Please also provide information about your operating system and Cantera version. This + will enable other members of the group to efficiently understand the problem and offer + suggestions on how to fix it. +- *Please do not post screenshots of code or error messages!* They cannot be searched by + anyone looking to solve a similar problem, and also cannot be read by text readers for + visually impaired users. Instead, please copy and paste any relevant text directly + into your message. Thanks! + +## Interacting with the Cantera Community + +### Code of Conduct + +All online and in-person interactions and communications related to Cantera are governed +by the [Cantera Code of Conduct](https://github.com/Cantera/cantera/blob/main/CODE_OF_CONDUCT.md). +This code of conduct sets expectations for the community to ensure that users and +contributors are able to participate in a respectful and welcoming environment. + +Please adhere to this code of conduct in any interactions you have in the Cantera +community. It is strictly enforced on all official Cantera repositories, websites, +users' group, and other resources. If you encounter someone violating these terms, +please [contact the code of conduct team](mailto:conduct@cantera.org) +([@speth](https://github.com/speth), [@bryanwweber](https://github.com/bryanwweber), and +[@kyleniemeyer](https://github.com/kyleniemeyer)) and we will address it as soon as +possible. + +### Contributing Code + +If there is a feature you would like to see added to Cantera, please consider becoming +part of the developer community and contributing code! +[Cantera's code repository](https://github.com/Cantera/cantera) is developed openly on +[GitHub](https://github.com/). Contributions are welcomed from anyone in the community; +please see the [Contributors' guide](https://github.com/Cantera/cantera/blob/main/CONTRIBUTING.md) +for assistance in getting started. There are also plenty of current contributors who are +happy to help, if you do not know how to get started. + +### Bug Reporting + +**What should I do if I think I've found a bug in Cantera?** + +- Check to see if you're using the most recent version of Cantera, and + upgrade if not. +- Check the [Issue Tracker](https://github.com/Cantera/cantera/issues) to see if the + issue has already been reported. +- Try to generate a [minimal, complete, and verifiable example](https://stackoverflow.com/help/mcve) + that demonstrates the observed bug. +- Create a new issue on the tracker (the "New Issue" button is toward the upper + right-hand corner, just above the list of open issues). Include as much information as + possible about your system configuration (operating system, compiler versions, Python + versions, installation method, etc.) + +**What information should I include in my bug report?** + +- The version of Cantera are you using, and how you installed it +- The operating system you are using +- If you compiled Cantera, what compiler you used, and what compilation options you + specified +- The version of Python or Matlab are you using, if applicable +- The necessary *input* to generate the reported behavior +- The full text of any error message you receive + +## Supporting Cantera + +### Citing Cantera + +If you use Cantera in a publication, we would appreciate if you cited the version of +Cantera that you used. This helps to improve the reproducibility of your work, as well +as giving credit to the many [authors](https://github.com/Cantera/cantera/blob/main/AUTHORS) +who have contributed their time to developing Cantera. The recommended citation for +Cantera is as follows: + +> David G. Goodwin, Harry K. Moffat, Ingmar Schoegl, Raymond L. Speth, and Bryan W. +> Weber. *Cantera: An object-oriented software toolkit for chemical kinetics, +> thermodynamics, and transport processes*. <https://www.cantera.org>, +> 2023. Version 3.0.0. doi:10.5281/zenodo.8137090 + +The following BibTeX entry may also be used: + +```bibtex +@misc{cantera, + author = "David G. Goodwin and Harry K. Moffat and Ingmar Schoegl and Raymond L. + Speth and Bryan W. Weber", + title = "Cantera: An Object-oriented Software Toolkit for Chemical + Kinetics, Thermodynamics, and Transport Processes", + year = 2023, + note = "Version 3.0.0", + howpublished = "\url{https://www.cantera.org}", + doi = {10.5281/zenodo.8137090} +} +``` + +If you are using a different version of Cantera, update the `year`, `note` and `doi` +fields accordingly. You can find the correct DOI for other versions of Cantera in +[Cantera's Zenodo Entry](https://doi.org/10.5281/zenodo.742000). + +### Donations + +Finally, please consider financially supporting Cantera's development! Cantera is a +fiscally sponsored project of NumFOCUS, a 501(c)3 nonprofit dedicated to supporting the +open source scientific computing community. If you have found Cantera to be useful to +your research or company, please consider making a +[donation](https://numfocus.org/donate-to-cantera) to support our efforts. All donations +will be used exclusively to fund the development of Cantera's source code, +documentation, or community. + +::::{grid} 1 2 2 2 + +:::{grid-item} +```{image} _static/img/SponsoredProject.png +:align: center +:alt: Powered by NumFOCUS +:target: https://numfocus.org +:width: 250px +``` +::: + +:::{grid-item} +```{button-link} https://numfocus.org/donate-to-cantera +:color: primary +:shadow: +:align: center +Donate to Cantera {octicon}`link-external` +``` +::: + +:::: + +:::{toctree} +:maxdepth: 1 +:hidden: + +News <news-index> +Affiliated Packages <affiliated> +Governance <governance> +Dave Goodwin <dave-goodwin> +::: diff --git a/source/conf.py b/source/conf.py new file mode 100644 index 000000000..1dcda720d --- /dev/null +++ b/source/conf.py @@ -0,0 +1,150 @@ +from __future__ import annotations + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import sys +from pathlib import Path + +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +sys.path.insert(0, str(Path(__file__).parent.resolve())) +needs_sphinx = "6.2" + + +# -- Project information ----------------------------------------------------- + +project = "Cantera" +copyright = "2024, Cantera Developers" +author = "Cantera Developers" +html_title = "Cantera" + +source_suffix = { + ".rst": "restructuredtext", + ".txt": "restructuredtext", + ".md": "markdown", +} + +# Print warnings into the built HTML files +keep_warnings = True + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx_design", + "myst_parser", + "sphinx.ext.duration", + "sphinx.ext.mathjax", + "sphinxcontrib.mermaid", + "ablog", + "sphinx.ext.intersphinx", +] + +myst_enable_extensions = ["colon_fence", "deflist", "attrs_block", "attrs_inline"] +myst_url_schemes = { + "http": None, + "https": None, + "mailto": {"url": "mailto:{{path}}", "title": "{{path}}"}, +} +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ["files"] +html_extra_path = ["files/license/license.txt", "files/surveys/"] + +root_doc = "index" + +# -- Internationalization --------------------------------------------------- +language = "en" + +intersphinx_mapping = { + 'stable': ('https://cantera.org/stable', None), + 'dev': ('https://cantera.org/dev', None), + 'ct30': ('https://cantera.org/3.0/sphinx/html', None), + 'ct26': ('https://cantera.org/2.6/sphinx/html', None), +} + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "pydata_sphinx_theme" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] +html_logo = "_static/img/cantera-logo.png" +html_favicon = "_static/img/favicon.png" +html_css_files = ["css/custom.css"] +html_js_files = ["js/copybutton.js"] +html_sidebars: dict[str, list | list[str]] = { + "index": [], + "news/**": [ + 'ablog/postcard.html', 'ablog/recentposts.html', + 'ablog/tagcloud.html'] +} +html_theme_options = { + "navbar_align": "left", + "navbar_center": ["initial-sections", "navbar-nav"], + "navbar_end": ["theme-switcher", "navbar-icon-links"], + # Search bar is overridden to the stable docs except for the "News" section + "navbar_persistent": ["search-button-field", "search-stable"], + + "show_prev_next": False, + "logo": { + "link": "/index.html", + "alt_text": "Cantera", + }, + "github_url": "https://github.com/Cantera/cantera", + "header_links_before_dropdown": 6, + # "logo": { + # "text": "PyData Theme", + # "image_dark": "_static/logo-dark.svg", + # "alt_text": "PyData Theme", + # }, + "use_edit_page_button": True, + "show_toc_level": 1, + # [left, content, right] For testing that the navbar items align properly + # "navbar_center": ["version-switcher", "navbar-nav"], + # "announcement": "https://raw.githubusercontent.com/pydata/pydata-sphinx-theme/main/docs/_templates/custom-template.html", + # "show_nav_level": 2, + # "navbar_start": ["navbar-logo"], + # "navbar_end": ["theme-switcher", "navbar-icon-links"], + # "navbar_persistent": ["search-button"], + # "primary_sidebar_end": ["custom-template.html", "sidebar-ethical-ads.html"], + # "article_footer_items": ["prev-next.html", "test.html", "test.html"], + # "content_footer_items": ["prev-next.html", "test.html", "test.html"], + # "footer_start": ["test.html", "test.html"], + # "secondary_sidebar_items": ["page-toc.html"], # Remove the source buttons + # "switcher": { + # "json_url": json_url, + # "version_match": version_match, + # }, +} +html_context = { + "github_user": "cantera", + "github_repo": "cantera", + "github_version": "main", + "doc_path": "docs", +} + +# ABlog options +blog_path = "news" +blog_title = "Cantera News" +blog_baseurl = "https://cantera.org" +blog_post_pattern = "news/*" diff --git a/source/dave-goodwin.md b/source/dave-goodwin.md new file mode 100644 index 000000000..d6cd6e025 --- /dev/null +++ b/source/dave-goodwin.md @@ -0,0 +1,95 @@ +--- +html_theme.sidebar_secondary.remove: true +--- + +# In Memoriam: Dave Goodwin + +::::{grid} 1 2 2 2 + +:::{grid-item} +:child-align: center + +*"Keep on working to make this world a better place. It is important to get your +thoughts away from your problems and focused on those who are less fortunate than you +are."* + +*"We can't control the hand of cards we are dealt, but we sure can determine how we +play them."* + +::: + +:::{grid-item} +```{figure} _static/images/dave-goodwin.jpg +:align: center +:alt: Dave Goodwin +:scale: 50 + +Prof. David Goodwin,\ +Original Developer of Cantera\ +*1957–2012* +``` +::: + + +:::: +Dave Goodwin, the original developer of Cantera, passed away in 2012. We would like to +provide this page for his friends and colleagues to salute his efforts at developing an +open-source constitutive modeling package. Caltech also wrote a +[lengthy article about Dave's life and work](http://www.caltech.edu/news/caltech-mourns-passing-david-g-goodwin-37485). +Please submit your thoughts and remembrances about Dave for inclusion on this page. + + +{attribution="Harry Moffat"} +> I know that the development of Cantera was a real passion for Dave, an advocacy for +> which went way beyond just his normal professional life. I think that whole community +> owes Dave a debt of gratitude in getting Cantera off of the ground and that the debt is +> best paid by continuing to develop Cantera along the principles that he so fervently +> espoused. +> +> Dave started off by with an extensive overhaul of the Chemkin suite of programs for +> gas-phase thermochemistry and kinetics. Chemkin had originally been developed at Sandia +> National Laboratories in the 1970s and had quickly gone into worldwide use. Dave became +> interested in overhauling Chemkin for two primary reasons. The first reason was that, +> mostly because of its success, Chemkin became a for-profit product whose distribution +> rights was licensed out during the nineties. Dave was very passionate about the +> open-source movement and about the necessity of keeping software for academic use as +> being in the public domain. Dave chose Cantera's licensing approach, Berkeley license, +> with this in mind. +> +> The second reason was that Dave saw the need to upgrade the modeling software to an +> object-oriented structure, which could then be extended easily to new constitutive +> models and situations. Dave had a strong passion for making sure his software kept up +> with the times, and advocated for the current multi-interface structure that Cantera +> currently has. Along the way he developed a new formalism for calculating the collision +> integrals used in the evaluation of transport parameters from dilute ideal gases theory. +> +> I first became aware of Dave's contributions through his groundbreaking work on diamond +> CVD. I remember reading his papers on the subject and marveling at how understanding the +> detailed kinetics of surface processes could directly lead to a real understanding of +> the performance of diamond growth reactors. That work probably was done with Cantera, +> and probably helped to direct the structure and content of Dave's original formulation +> of Cantera. + +{attribution="smjaffe11, Dec 6, 2012"} +> A couple Christmas seasons before Dave died, we were visiting in his home. One side of +> his body was paralyzed by a glioma, the other side gripped by Parkinson's. I asked +> Dave if he was bitter about his infirmity. He simply said, “I’ve got no time for +> anger.” The next Christmas I was thinking about Dave's paintings. Many hung in his +> living room, and there was one I remembered in his grad school office that Richard +> Diebenkorn would have been proud to sign. Dave's home is a few minutes from the +> Norton-Simon art museum. Impromptu Dave, Frances, and I threw the wheel chair in the +> trunk, and went. A big storm had just felled a large tree in the sculpture garden. +> Frances' manner impressed me. Perhaps ancient wisdom or medical training enabled her +> to at once care for Dave and treat him as an independent equal. Dave and Frances +> brought equanimity to life’s rewards and responsibilities. Much thanks. You are in our +> hearts. + +{attribution="jasonkholt, Dec 13, 2012"} +> Dave was my co-advisor during my PhD work at Caltech from 1997-2002, and I benefitted +> greatly from my weekly meetings with him. His work on developing Cantera was an +> integral part of the modeling component to my thesis on polycrystalline silicon CVD, +> but more broadly his effort to democratize this information has proven to be hugely +> valuable to a number of communities. While I no longer work in this space since +> leaving Caltech, I sincerely hope that other researchers for whom this package is +> valuable continue to make contributions and refinements. Dave will be greatly missed +> and my thoughts are with his family. diff --git a/files/license/license.txt b/source/files/license/license.txt similarity index 100% rename from files/license/license.txt rename to source/files/license/license.txt diff --git a/files/survey2013/compilers.png b/source/files/surveys/survey2013/compilers.png similarity index 100% rename from files/survey2013/compilers.png rename to source/files/surveys/survey2013/compilers.png diff --git a/files/survey2013/dependencies.png b/source/files/surveys/survey2013/dependencies.png similarity index 100% rename from files/survey2013/dependencies.png rename to source/files/surveys/survey2013/dependencies.png diff --git a/files/survey2013/development-focus.png b/source/files/surveys/survey2013/development-focus.png similarity index 100% rename from files/survey2013/development-focus.png rename to source/files/surveys/survey2013/development-focus.png diff --git a/files/survey2013/equilibrium-solvers.png b/source/files/surveys/survey2013/equilibrium-solvers.png similarity index 100% rename from files/survey2013/equilibrium-solvers.png rename to source/files/surveys/survey2013/equilibrium-solvers.png diff --git a/files/survey2013/help-resources.png b/source/files/surveys/survey2013/help-resources.png similarity index 100% rename from files/survey2013/help-resources.png rename to source/files/surveys/survey2013/help-resources.png diff --git a/files/survey2013/install-method.png b/source/files/surveys/survey2013/install-method.png similarity index 100% rename from files/survey2013/install-method.png rename to source/files/surveys/survey2013/install-method.png diff --git a/files/survey2013/language-interfaces.png b/source/files/surveys/survey2013/language-interfaces.png similarity index 100% rename from files/survey2013/language-interfaces.png rename to source/files/surveys/survey2013/language-interfaces.png diff --git a/files/survey2013/libraries-available.png b/source/files/surveys/survey2013/libraries-available.png similarity index 100% rename from files/survey2013/libraries-available.png rename to source/files/surveys/survey2013/libraries-available.png diff --git a/files/survey2013/major-features.png b/source/files/surveys/survey2013/major-features.png similarity index 100% rename from files/survey2013/major-features.png rename to source/files/surveys/survey2013/major-features.png diff --git a/files/survey2013/new-features.png b/source/files/surveys/survey2013/new-features.png similarity index 100% rename from files/survey2013/new-features.png rename to source/files/surveys/survey2013/new-features.png diff --git a/files/survey2013/onedim-features.png b/source/files/surveys/survey2013/onedim-features.png similarity index 100% rename from files/survey2013/onedim-features.png rename to source/files/surveys/survey2013/onedim-features.png diff --git a/files/survey2013/operating-system.png b/source/files/surveys/survey2013/operating-system.png similarity index 100% rename from files/survey2013/operating-system.png rename to source/files/surveys/survey2013/operating-system.png diff --git a/files/survey2013/paid-development.png b/source/files/surveys/survey2013/paid-development.png similarity index 100% rename from files/survey2013/paid-development.png rename to source/files/surveys/survey2013/paid-development.png diff --git a/files/survey2013/paid-support.png b/source/files/surveys/survey2013/paid-support.png similarity index 100% rename from files/survey2013/paid-support.png rename to source/files/surveys/survey2013/paid-support.png diff --git a/files/survey2013/python-packages-available.png b/source/files/surveys/survey2013/python-packages-available.png similarity index 100% rename from files/survey2013/python-packages-available.png rename to source/files/surveys/survey2013/python-packages-available.png diff --git a/files/survey2013/python-version.png b/source/files/surveys/survey2013/python-version.png similarity index 100% rename from files/survey2013/python-version.png rename to source/files/surveys/survey2013/python-version.png diff --git a/files/survey2013/reactor-features.png b/source/files/surveys/survey2013/reactor-features.png similarity index 100% rename from files/survey2013/reactor-features.png rename to source/files/surveys/survey2013/reactor-features.png diff --git a/files/survey2013/thermo-models.png b/source/files/surveys/survey2013/thermo-models.png similarity index 100% rename from files/survey2013/thermo-models.png rename to source/files/surveys/survey2013/thermo-models.png diff --git a/files/survey2013/transport-models.png b/source/files/surveys/survey2013/transport-models.png similarity index 100% rename from files/survey2013/transport-models.png rename to source/files/surveys/survey2013/transport-models.png diff --git a/files/survey2013/usage-environment.png b/source/files/surveys/survey2013/usage-environment.png similarity index 100% rename from files/survey2013/usage-environment.png rename to source/files/surveys/survey2013/usage-environment.png diff --git a/source/governance.md b/source/governance.md new file mode 100644 index 000000000..89037cef3 --- /dev/null +++ b/source/governance.md @@ -0,0 +1,71 @@ +# Cantera Governance + +This document outlines the policies and procedures that manage the Cantera community. + +## Code of Conduct + +All online and in-person interactions and communications related to Cantera are governed +by the [Cantera Code of Conduct](https://github.com/Cantera/cantera/blob/main/CODE_OF_CONDUCT.md). +This code of conduct sets expectations for the community to ensure that users and +contributors are able to participate in a respectful and welcoming environment. + +## Teams & Roles + +Steering Committee +: This is the governing body of Cantera, making decisions regarding the structure, + operations, and long-term direction of the project. Each member has one vote for + important project decisions. + +Committers +: Members of the committers team have commit/push access to the Cantera source code, + and can merge pull requests. + +Cantera Users' Group moderators +: Members of the moderators team moderate the Users' Group, and have power to + enable/disable posting of community members at their discretion. + +(current-steering-committee)= +## Current Steering Committee + +The role of the steering committee is to ensure the long-term health of the Cantera +project. This includes overseeing the development of the Cantera code and community in a +way that most benefits the entire community of users and contributors. The steering +committee can be contacted at [steering@cantera.org](mailto:steering@cantera.org). The +current steering committee (in alphabetical order) is: + +- Steven DeCaluwe (2018–) +- Connie Gao (2019-) +- C. Franklin Goldsmith (2018–) +- Kyle Niemeyer (2018–) +- Raymond Speth (2018–) +- Bryan Weber (2018–) +- Richard West (2018–) + +The Steering Committee should have at least five members. Members serve in two-year +cycles (starting in November 2018), with the ability to reaffirm their membership at the +end of each cycle without a committee vote or leave the committee at their discretion. +Members can also choose to leave the committee at any time. + +## Voting + +The Steering Committee will vote on the following topics, with passing contingent on a +2/3 majority. All members should vote, but abstentions are permitted. + +- Modifications of the governance procedures +- Adding/removing steering committee members +- Spending project funds +- Adding/removing people with commit rights to GitHub repositories +- Adding/removing moderators of the User’s Group +- Adding/removing people to private communication channels +- Adding/removing people with rights to post as Cantera on social media +- Establishing sub-committees and roles +- Adding/removing members from the Scientific Advisory Board + +The Steering Committee will maintain a Google Doc that records all votes (but not +discussion). Access to the Google Doc will be limited to members of the Steering +Committee. + +## Acknowledgements + +This document was inspired by the +[conda-forge governance guidelines](https://conda-forge.org/docs/orga/governance.html). diff --git a/source/index.md b/source/index.md new file mode 100644 index 000000000..66c8a4ecf --- /dev/null +++ b/source/index.md @@ -0,0 +1,196 @@ +--- +myst: + html_meta: + "description lang=en": | + Cantera is an open-source suite of tools for problems involving chemical kinetics, thermodynamics, and transport processes. +html_theme.sidebar_secondary.remove: true +--- + +<!-- The following workaround is used to set the HTML page title --> +<div style="visibility: hidden; display: none;"> + +# Open-source chemical kinetics, thermodynamics, and transport + +</div> + +<p class="jumbotron-text">Cantera is an open-source suite of tools for problems involving chemical kinetics, thermodynamics, and transport processes.</p> + +::::{grid} 1 2 2 4 + +:::{grid-item} + +#### Automation + +Cantera automates the chemical kinetic, thermodynamic, and transport calculations so that the users can efficiently incorporate detailed chemical thermo-kinetics and transport models into their calculations. +::: + +:::{grid-item} + +#### Object-Oriented + +Cantera utilizes object-oriented concepts for robust yet flexible phase models, and algorithms are generalized so that users can explore different phase models with minimal changes to their overall code. +::: + +:::{grid-item} + +#### Multiple Interfaces + +Cantera can be used from Python and Matlab, or in applications written in C/C++ and Fortran 90. +::: + +:::{grid-item} + +#### Broad Applications + +Cantera is currently used for applications including combustion, detonations, electrochemical energy conversion and storage, fuel cells, batteries, aqueous electrolyte solutions, plasmas, and thin film deposition. +::: +:::: + +::::::{grid} 1 + +:::::{grid-item} + +::::{grid} 1 1 3 3 + +:::{grid-item-card} <a href="stable/userguide/index.html#introductory-tutorials">Tutorials</a> + +_Where do I get started?_ The tutorials linked below will get you started using Cantera +on your own machine. + +{bdg-link-primary}`Python <stable/userguide/python-tutorial.html>` +{bdg-link-primary}`Convert Input Files <stable/userguide/ck2yaml-tutorial.html>` + +::: + +:::{grid-item-card} <a href="stable/examples/index.html">Examples</a> + +_What can Cantera do?_ We have a number of examples demonstrating the use of Cantera in +some of our interfaces. + +{bdg-link-primary}`Python <stable/examples/python/index.html>` +{bdg-link-primary}`Matlab (experimental)<stable/examples/matlab_experimental/index.html>` +{bdg-link-primary}`C++ <stable/examples/cxx/index.html>` +::: + +:::{grid-item-card} <a href="stable/install/index.html">Install</a> + +_How do I install Cantera?_ Instructions for installing pre-built Cantera binaries can +be found here. + +{bdg-link-primary}`Conda <stable/install/conda.html>` +{bdg-link-primary}`Pip <stable/install/pip.html>` +{bdg-link-primary}`Ubuntu <stable/install/ubuntu.html>` +{bdg-link-primary}`Compile from source <stable/develop/index.html#compiling-cantera-from-source>` + +::: +:::: +::::: + +:::::{grid-item} + +::::{grid} 1 1 3 3 + +:::{grid-item-card} <a href="stable/reference/index.html#science-reference">Science Reference</a> + +_What equations does Cantera solve?_ Descriptions of the models implemented by Cantera, +including equations of state, energy and mass conservation, and chemical kinetics. + +{bdg-link-primary}`Thermodynamics <stable/reference/thermo/index.html>` +{bdg-link-primary}`Kinetics <stable/reference/kinetics/index.html>` +{bdg-link-primary}`Transport <stable/reference/transport/index.html>` +{bdg-link-primary}`Reactors <stable/reference/reactors/index.html>` +{bdg-link-primary}`1D Flames <stable/reference/onedim/index.html>` + +::: + +:::{grid-item-card} <a href="stable/reference/index.html#programming-reference">Programming Reference</a> + +_How do I use Cantera's capabilities_? Documentation for the classes and functions that +make up Cantera. + +{bdg-link-primary}`Python <stable/python/index.html>` +{bdg-link-primary}`C++ <stable/cxx/index.html>` +{bdg-link-primary}`Matlab <stable/matlab/index.html>` +{bdg-link-primary}`YAML <stable/yaml/index.html>` +::: + +:::{grid-item-card} <a href="https://mybinder.org/v2/gh/Cantera/cantera-jupyter/main">Try Cantera in Your Browser!</a> + +The Binder service allows you to try out Cantera in the cloud without installing it on +your computer. You'll see some of our examples and be able to run them yourself! + +<a href="https://mybinder.org/v2/gh/Cantera/cantera-jupyter/main" rel="nofollow" class="card-link"> +<img src="https://mybinder.org/badge_logo.svg" alt="Binder" +data-canonical-src="https://mybinder.org/badge_logo.svg" style="max-width:100%;"> +</a> +::: +:::: +::::: +:::::: + +::::::{grid} 1 1 2 2 +:::::{grid-item} + +<h2 class="text-center" style="magin-bottom: 20px">Connect With Cantera</h2> + +::::{grid} 2 +:::{grid-item} +:columns: 9 +The <a href="https://groups.google.com/g/cantera-users">Cantera Users’ Group</a> on Google Groups is the forum where most Cantera users have their questions asked and answered. If you need help using Cantera and cannot find an answer in the tutorials or documentation at Cantera's website, consider joining and asking a question there. Find more information in our <a href="/community.html#the-cantera-users-group">Community section</a>. +::: +:::{grid-item} +:columns: 3 +<a href="https://groups.google.com/g/cantera-users" rel="nofollow"> +<img alt="Google Groups" class="align-center" src="/_static/img/Groups_Logo.png" style="width: 100px;"> +</a> +::: +:::: +::::{grid} 2 +:::{grid-item} +:columns: 9 +Cantera is developed by a team of volunteers, and we're always looking for new team members. If there is a feature you want added, a bug that needs to be fixed, or even just a typo in the documentation, changes from the community are always welcome. For more, see the section about <a href="/community.html#contributing-code" title="Contributing Code">contributing code</a> on our Community page. +::: +:::{grid-item} +:columns: 3 + +<a href="https://github.com/Cantera/cantera" rel="nofollow"> +<img alt="GitHub" class="align-center" src="/_static/img/Git_Logo.png" style="width: 100px;"> +</a> +::: +:::: +::::: +:::::{grid-item} + +<h2 class="text-center" style="magin-bottom: 20px">How is Cantera Supported?</h2> + +Cantera is a Sponsored Project of NumFOCUS, a 501(c)(3) nonprofit charity in the United States. NumFOCUS provides Cantera with fiscal, legal, and administrative support to help ensure the health and sustainability of the project. Visit <a href="https://numfocus.org">numfocus.org</a> for more information. + +Donations to Cantera are managed by NumFOCUS. For donors in the United States, your gift is tax-deductible to the extent provided by law. As with any donation, you should consult with your tax adviser about your particular tax situation. + +If you have found Cantera to be useful to your research or company, please consider making a <a href="https://numfocus.org/donate-to-cantera" title="Donate to Cantera" rel="nofollow">donation</a> to support our efforts. All donations will be used exclusively to fund the development of Cantera's source code, documentation, or community. + +```{image} /_static/img/SponsoredProject.png +:alt: Powered by NumFOCUS +:target: https://numfocus.org +:width: 250px +:align: center +``` + +  + +```{button-link} https://numfocus.org/donate-to-cantera +:align: center +:color: secondary +:shadow: +Donate to Cantera {octicon}`link-external` +``` +::::: +:::::: + + +:::{toctree} +:maxdepth: 1 +:hidden: + +Community <community> +::: diff --git a/source/news-index.md b/source/news-index.md new file mode 100644 index 000000000..c3693dbfb --- /dev/null +++ b/source/news-index.md @@ -0,0 +1,11 @@ +# News + +{bdg-ref-primary}`Posts by tag <blog-tags>` +{bdg-ref-primary}`Posts by author <blog-authors>` + +```{postlist} +:date: "%A, %B %d, %Y" +:list-style: circle +:format: "{title} by {author} on {date}" +:excerpts: +``` diff --git a/posts/GSoC_2019_Fourth_Blog.md b/source/news/GSoC_2019_Fourth_Blog.md similarity index 66% rename from posts/GSoC_2019_Fourth_Blog.md rename to source/news/GSoC_2019_Fourth_Blog.md index bff6a13a9..730bce43f 100644 --- a/posts/GSoC_2019_Fourth_Blog.md +++ b/source/news/GSoC_2019_Fourth_Blog.md @@ -1,19 +1,12 @@ --- -title: GSoC 2019 Fourth Blog -date: 2019-07-20 15:03 UTC-19:03 -slug: GSoC_2019_Fourth_Blog +date: 2019-07-20 15:03 tags: GSoC 2019 -description: 2019 Google Summer of Code Cantera Project Blog -type: text author: Chao Xu --- # GSoC 2019 Fourth Blog -After two months, the functions of ChemCheck are fairly robust. We improved editing and ck2yaml error reporting pages this week, and we -added pages for user account management. - -<!-- TEASER_END --> +After two months, the functions of ChemCheck are fairly robust. We improved editing and ck2yaml error reporting pages this week, and we added pages for user account management. We have included a download function for the editing page, so users can download the edited file to their local directory. It would be more convenient if changes can be saved to the original file online, so that users do not have to re-upload their files, but we will leave it for now since an @@ -21,28 +14,48 @@ editing function is not the most important part. The current exception handling be recognized by ace-editor, and it could also be improved by implementing some Python library to guess the encoding of the file in the future. Here is what the page looks like: -{{% thumbnail "/images/GSoC_2019_images/updated_editor.png" alt="Updated Editor Page" align="center" %}}<p class="text-center">Editor Page</p>{{% /thumbnail %}} +:::{card} Updated Editor Page +```{image} /_static/images/GSoC_2019_images/updated_editor.png +:align: center +:width: 100% +``` +::: + The page shown when conversion fails is also improved. Logging messages are added to error messages if a conversion failed. In addition, ChemCheck looks through four lines ahead and after the line where the error occurs, so that users could have an idea about how to fix the error. Here is the page: -{{% thumbnail "/images/GSoC_2019_images/convert_fail_page.png" alt="Convert Fail Page" align="center" %}}<p class="text-center">Convert Fail Page</p>{{% /thumbnail %}} +:::{card} Convert Fail Page +```{image} /_static/images/GSoC_2019_images/convert_fail_page.png +:align: center +:width: 100% +``` +::: A series of account management pages including signup page, login page, logout page, password change page (changing password for users who are logged in), and password reset (for users who forget their password) pages, among others. have been included. The signup function will be used only if users want to retrieve their uploaded files. A built-in Django module (`django.contrib.auth.urls`) is implemented for this part; however, the password reset page did not work as expected, because it did not send an email to the user to reset the password. I am working on getting this part to work. Except the password reset function, other pages work well. -Signup Page: - -{{% thumbnail "/images/GSoC_2019_images/signup.png" alt="Signup Page" align="center" %}}<p class="text-center">Signup Page</p>{{% /thumbnail %}} - -Login Page: - -{{% thumbnail "/images/GSoC_2019_images/login.png" alt="Login Page" align="center" %}}<p class="text-center">Login Page</p>{{% /thumbnail %}} - -Password Change Page: - -{{% thumbnail "/images/GSoC_2019_images/password_change.png" alt="Password Change Page" align="center" %}}<p class="text-center">Password Change Page</p>{{% /thumbnail %}} +:::{card} Signup Page +```{image} /_static/images/GSoC_2019_images/signup.png +:align: center +:width: 100% +``` +::: + +:::{card} Login Page +```{image} /_static/images/GSoC_2019_images/login.png +:align: center +:width: 100% +``` +::: + +:::{card} Password Change Page +```{image} /_static/images/GSoC_2019_images/password_change.png +:align: center +:width: 100% +``` +::: ## Goals in next two weeks diff --git a/posts/GSoC_2019_Project_First_Evaluation.md b/source/news/GSoC_2019_Project_First_Evaluation.md similarity index 79% rename from posts/GSoC_2019_Project_First_Evaluation.md rename to source/news/GSoC_2019_Project_First_Evaluation.md index 899be4eb3..b3b18cfd6 100644 --- a/posts/GSoC_2019_Project_First_Evaluation.md +++ b/source/news/GSoC_2019_Project_First_Evaluation.md @@ -1,10 +1,6 @@ --- -title: GSoC 2019 First Evaluation -date: 2019-06-22 17:41 UTC-21:41 -slug: GSoC_2019_Project_First_Evaluation +date: 2019-06-22 17:41 tags: GSoC 2019 -description: 2019 Google Summer of Code Cantera Project Blog -type: text author: Chao Xu --- @@ -17,39 +13,62 @@ web-based application for visualizing and diagnosing syntax and chemical errors functions that allow users to convert their mechanism files to Cantera YAML input files easily (Cantera input file is going to be changed from CTI file to YAML file, so we made some adjustments as well). -<!-- TEASER_END --> - ## Upload Page Users will upload their files to ChemCheck for checking, so we created an upload page which allows users to upload their mechanism, transport, thermo, and surface file. Here is the view of upload page. -{{% thumbnail "/images/GSoC_2019_images/upload_page.png" alt="Upload Page" align="center" %}}<p class="text-center">Upload Page</p>{{% /thumbnail %}} +:::{card} Upload Page +```{image} /_static/images/GSoC_2019_images/upload_page.png +:align: center +:width: 100% +``` +::: ## List Page After files are uploaded, ChemCheck returns to a list page which lists all uploaded files in the app with id for each group of files. Users are able to either click on "Details" button to do further operation to their files or hit "Upload new mechanism" button to upload new files. -{{% thumbnail "/images/GSoC_2019_images/list_page.png" alt="List Page" align="center" %}}<p class="text-center">List Page</p>{{% /thumbnail %}} +:::{card} List Page +```{image} /_static/images/GSoC_2019_images/list_page.png +:align: center +:width: 100% +``` +::: ## Detail Page In this page, users can either edit their files or hit the "convert to YAML" button to convert files. The editing function is still in development. Also, there is a "Back to mechanism list" link for users going back to list view. -{{% thumbnail "/images/GSoC_2019_images/detail_page.png" alt="Detail Page" align="center" %}}<p class="text-center">Detail Page</p>{{% /thumbnail %}} +:::{card} Detail Page +```{image} /_static/images/GSoC_2019_images/detail_page.png +:align: center +:width: 100% +``` +::: ## Convert Page If the file is converted successfully, a success message will be shown on the page. Users can see details and download the files from this page. -{{% thumbnail "/images/GSoC_2019_images/convert_success.png" alt="Convert Success Page" align="center" %}}<p class="text-center">Convert Success Page</p>{{% /thumbnail %}} +:::{card} Convert Success Page +```{image} /_static/images/GSoC_2019_images/convert_success.png +:align: center +:width: 100% +``` +::: However, if the file is not converted successfully, the error message will be shown. -{{% thumbnail "/images/GSoC_2019_images/convert_fail.png" alt="Convert Fail Page" align="center" %}}<p class="text-center">Convert Fail Page</p>{{% /thumbnail %}} +:::{card} Convert Fail Page +```{image} /_static/images/GSoC_2019_images/convert_fail.png +:align: center +:width: 100% +``` +::: ## Future Improvement diff --git a/posts/GSoC_2019_Project_Introduction.md b/source/news/GSoC_2019_Project_Introduction.md similarity index 79% rename from posts/GSoC_2019_Project_Introduction.md rename to source/news/GSoC_2019_Project_Introduction.md index 45a2ca6e7..7bf46cf3a 100644 --- a/posts/GSoC_2019_Project_Introduction.md +++ b/source/news/GSoC_2019_Project_Introduction.md @@ -1,18 +1,12 @@ --- -title: GSoC 2019 PyCanChemAndYouCan2 -date: 2019-06-07 12:33:00 UTC-16:33 -slug: GSoC_2019_Project_Introduction +date: 2019-06-07 12:33 tags: GSoC 2019 -description: 2019 Google Summer of Code Cnatera Project Blog -type: text author: Chao Xu --- -# GSoC 2019 PyCanChemAndYouCan2 (ChemCheck) +# GSoC 2019: PyCanChemAndYouCan2 (ChemCheck) -Hi everyone! I'm Chao Xu, a master student in Chemical Engineering at Northeastern University. I am working on a Cantera project in GSoC 2019 with my mentor Richard West([@rwest](https://github.com/rwest)) and other Cantera committee members([@bryanwweber](https://github.com/bryanwweber), [@kyleniemeyer](https://github.com/kyleniemeyer)). I am glad to introduce my project here! - -<!-- TEASER_END --> +Hi everyone! I'm Chao Xu, a master student in Chemical Engineering at Northeastern University. I am working on a Cantera project in GSoC 2019 with my mentor Richard West ([@rwest](https://github.com/rwest)) and other Cantera committee members ([@bryanwweber](https://github.com/bryanwweber), [@kyleniemeyer](https://github.com/kyleniemeyer)). I am glad to introduce my project here! ## What is PyCanChemAndYouCan2(ChemCheck) @@ -53,9 +47,15 @@ The debugging tool PyCanChemAndYouCan2 is a web-based application developed in D Here is the workflow of the application: - [upload files] --> [list files] --> [choose one and execute by ck2cti.py and wrapper script] - --> [show input file with added comments on ACE editor] --> [edit file] --> [download edited file] +```{mermaid} +flowchart TB + A[upload files] --> B[list files] + B --> C[choose one and execute by ck2cti.py and wrapper script] + C --> D[show input file with added comments on ACE editor] + D --> E[edit file] + E --> F[download edited file] +``` My project code will be posted on <https://github.com/comocheng/ChemCheck>. -Please feel free to post your suggestions about this project on the [Cantera group](https://groups.google.com/g/cantera-users), or email me <mailto:xu.chao@husky.neu.edu>. +Please feel free to post your suggestions about this project on the [Cantera group](https://groups.google.com/forum/#!forum/cantera-users), or email me <mailto:xu.chao@husky.neu.edu>. diff --git a/source/news/GSoC_2019_Third_Blog.md b/source/news/GSoC_2019_Third_Blog.md new file mode 100644 index 000000000..f8ce443d3 --- /dev/null +++ b/source/news/GSoC_2019_Third_Blog.md @@ -0,0 +1,62 @@ +--- +date: 2019-07-06 13:59 +tags: GSoC 2019 +author: Chao Xu +--- + +# GSoC Third Blog -- Function update + +As we planned after the first evaluation, the functionality of ChemCheck should be more robust. File replacement was added, and users are able to +update and delete files arbitrarily. + +The page looks like this: + +:::{card} Updated Detail Page +```{image} /_static/images/GSoC_2019_images/detail_page2.png +:align: center +:width: 100% +``` +::: + +The delete button leads to a delete page, which will delete files in both the database and the directory. + +:::{card} Delete Page +```{image} /_static/images/GSoC_2019_images/delete_page.png +:align: center +:width: 100% +``` +::: + +In the update page, users can either replace their files or delete it by checking "clear". + +:::{card} Update Page +```{image} /_static/images/GSoC_2019_images/update_page.png +:align: center +:width: 100% +``` +::: + +In addition to these, new features ChemCheck can provide the traceback message instead of only one line error. + +:::{card} Error Page +```{image} /_static/images/GSoC_2019_images/error_page.png +:align: center +:width: 100% +``` +::: + +An editing function is also included: + +:::{card} Editor Page +```{image} /_static/images/GSoC_2019_images/ace_editor.png +:align: center +:width: 100% +``` +::: + +## Next Steps + +I am working toward catching logging messages to make the error understandable and +making the error page look nicer. Also, I will improve editing function (adding download +function in editor page, and change highlight settings of ace editor). After that, I +will test different defective mechanism files and providing fix suggestions. diff --git a/posts/cantera-240-released.md b/source/news/cantera-240-released.md similarity index 91% rename from posts/cantera-240-released.md rename to source/news/cantera-240-released.md index 6cc7ab85c..a74b35566 100644 --- a/posts/cantera-240-released.md +++ b/source/news/cantera-240-released.md @@ -1,6 +1,6 @@ --- title: Cantera 2.4.0 -date: 2018-08-24 17:25:00 UTC-04:00 +date: 2018-08-24 17:25 slug: cantera-240-released tags: release description: The new Cantera release is here! @@ -32,12 +32,10 @@ contributions from 14 developers: [@speth](https://github.com/speth), [@vdevgan](https://github.com/vdevgan), [@KyleLinevitchJr](https://github.com/KyleLinevitchJr), and [@MarcDuQuesne](https://github.com/MarcDuQuesne). -<!-- TEASER_END --> - 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 +toolbox for macOS users, replacing Homebrew as the preferred method of installing Cantera for Matlab on macOS. Thanks to a small development grant from NumFOCUS (see more about NumFOCUS below), @@ -52,8 +50,8 @@ everyone. Cantera is now officially part of NumFOCUS. NumFOCUS is a 501(c)3 nonprofit dedicated to supporting the open source scientific computing community. If you are interested in learning more about -NumFOCUS, please visit their website at https://numfocus.org, or our website at -https://cantera.org/community.html#donations. +NumFOCUS, please visit their website at <https://numfocus.org>, or our website at +<https://cantera.org/community.html#donations>. Cantera 2.4.0 is the last release that will be compatible with Python 2.7. Support for Python 2.7 from the Python Software Foundation will [end January 1, @@ -74,7 +72,7 @@ page](https://github.com/Cantera/cantera/releases/tag/v2.4.0). Major changes are ### Bugs fixed -- Fix inconstencies and bugs in several `ThermoPhase` derived classes, including `PDSS_IdealGas`, `IonsFromNeutralVPSSTP`, `PDSS_IonsFromNeutral`, `PDSS_HKFT`, `LatticePhase`, `PDSS_SSVol`, `ConstDensityThermo`, and `PureFluidPhase` +- Fix inconsistencies and bugs in several `ThermoPhase` derived classes, including `PDSS_IdealGas`, `IonsFromNeutralVPSSTP`, `PDSS_IonsFromNeutral`, `PDSS_HKFT`, `LatticePhase`, `PDSS_SSVol`, `ConstDensityThermo`, and `PureFluidPhase` - Preserve constant property pair when multiplying `Quantity` objects - Fix using pure fluids in reactors - Add temperature dependence of rotational relaxation in transport calculations diff --git a/posts/default-branch.md b/source/news/default-branch.md similarity index 92% rename from posts/default-branch.md rename to source/news/default-branch.md index 41f0a8bba..7a1351c10 100644 --- a/posts/default-branch.md +++ b/source/news/default-branch.md @@ -1,13 +1,11 @@ --- -title: Renaming Cantera's default branch -date: 2020-07-10 17:33:00 UTC-05:00 -slug: default-branch +date: 2020-07-10 17:33 tags: git -description: Renaming Cantera's default branch -type: text author: Raymond Speth --- +# Renaming Cantera's default branch + There has been a growing awareness that the use of the name `master` for the default branch in Git repositories perpetuates the use of the language of oppression. It has also [been shown](https://mail.gnome.org/archives/desktop-devel-list/2019-May/msg00066.html) @@ -56,7 +54,7 @@ myfork git@github.com:your_username/cantera.git (fetch) myfork git@github.com:your_username/cantera.git (push) ``` -#### Case 1: tracked remote is `Cantera/cantera` +### Case 1: tracked remote is `Cantera/cantera` If the remote being tracked (in this example, `origin`) is the main Cantera repository, that is, `Cantera/cantera.git`, then you can set the `main` branch of `Cantera/cantera` as the upstream for your `main` branch: @@ -75,7 +73,7 @@ Then, you can push the updated main branch to your fork (in this example, $ git push main myfork ``` -#### Case 2: tracked remote is your fork +### Case 2: tracked remote is your fork If the remote listed is your fork of Cantera, then you may want to rename the branch on your fork as well. If the remote name for your fork is `myfork`, this @@ -85,7 +83,7 @@ can be changed by running: $ git push -u myfork main ``` -### Deleting the old branch from your fork +## Deleting the old branch from your fork Once you have pushed the new `main` branch to your fork, visit the GitHub website for your fork, go to **Settings**, then **Branches**, then diff --git a/posts/gsoc-2020-blog-1.md b/source/news/gsoc-2020-blog-1.md similarity index 68% rename from posts/gsoc-2020-blog-1.md rename to source/news/gsoc-2020-blog-1.md index 8064c48cd..1f4d04549 100644 --- a/posts/gsoc-2020-blog-1.md +++ b/source/news/gsoc-2020-blog-1.md @@ -1,28 +1,24 @@ --- -title: GSoC 2020 Blog Post 1 -date: 2020-06-15 14:00:00 UTC-04:00 -slug: gsoc-2020-blog-1 +date: 2020-06-15 14:00 tags: GSoC 2020 -description: A recap of work during weeks 1 & 2. -type: text author: Paul Blum --- -## _Developing a 0-D Steady-State Combustion Solver for Cantera_ +# GSoC 2020: Developing a 0-D Steady-State Combustion Solver for Cantera -### Learning C++ for Cantera Development +## Learning C++ for Cantera Development My original [project proposal](https://drive.google.com/file/d/1vaOjydm6wWKgF2M4J3iFwNZNKHX5laBY/view?usp=sharing) called for preliminary development in C and Python, primarily because I’ve worked with these languages in the past and would be able to start writing test code right away. However, I ultimately decided to learn and use C++ instead, and I’m very glad that I did. Most of the Cantera source code is written in C++, and being able to easily read and reference it without guessing at the syntax has proven invaluable in development so far. -I learned C++ by following a free [Codecademy tutorial](https://www.codecademy.com/learn/learn-c-plus-plus), which I would definitely recommend to beginning and experienced coders alike. The tutorial was detailed and interactive, and only took me a day to complete. After that, I followed Cantera’s [C++ Interface Tutorial](https://cantera.org/tutorials/cxx-guide/index.html), another excellent resource that I’d say is essential for any beginning Cantera developer. It introduced Cantera-specific technical details needed for C++ development, and provided simple code examples that illustrated how to use Cantera’s functionality to perform some basic calculations. +I learned C++ by following a free [Codecademy tutorial](https://www.codecademy.com/learn/learn-c-plus-plus), which I would definitely recommend to beginning and experienced coders alike. The tutorial was detailed and interactive, and only took me a day to complete. After that, I followed Cantera’s {doc}`C++ Interface Tutorial <stable:userguide/cxx-tutorial>`, another excellent resource that I’d say is essential for any beginning Cantera developer. It introduced Cantera-specific technical details needed for C++ development, and provided simple code examples that illustrated how to use Cantera’s functionality to perform some basic calculations. -### Switching Solvers +## Switching Solvers -The heart of this project is a capable numerical solver that can quickly provide a solution to the [set of nonlinear equations](https://drive.google.com/file/d/1vxt3tW1wbvMLTaDygRmpqEJN6yNSO_Lv/view?usp=sharing) that characterize 0-D steady-state combustion systems. In my project proposal I suggested the use of KINSOL, an externally developed code module that uses a version of Newton’s method to solve nonlinear algebraic equations. Stemming from discussions with mentors, I found that Cantera has a built-in and similarly implemented damped Newton solver that should be able to provide the equivalent capability. In efforts not to duplicate existing functionality, as well as to maintain consistency with the rest of the source code, I decided it would be best to use Cantera’s solver in this application. The solver was developed for solving 1-D multi-domain problems, but after some quick testing, I determined that it’s also able to solve 0-D problems with ease. These tests were performed by modifying the residual functions and a few input parameters in the [Blasius sample program](https://github.com/Cantera/cantera/blob/main/samples/cxx/bvp/blasius.cpp) to find solutions to arbitrary sets of equations at a single point, rather than along a 1-D array of points. +The heart of this project is a capable numerical solver that can quickly provide a solution to the [set of nonlinear equations](https://drive.google.com/file/d/1vxt3tW1wbvMLTaDygRmpqEJN6yNSO_Lv/view?usp=sharing) that characterize 0-D steady-state combustion systems. In my project proposal I suggested the use of KINSOL, an externally developed code module that uses a version of Newton’s method to solve nonlinear algebraic equations. Stemming from discussions with mentors, I found that Cantera has a built-in and similarly implemented damped Newton solver that should be able to provide the equivalent capability. In efforts not to duplicate existing functionality, as well as to maintain consistency with the rest of the source code, I decided it would be best to use Cantera’s solver in this application. The solver was developed for solving 1-D multi-domain problems, but after some quick testing, I determined that it’s also able to solve 0-D problems with ease. These tests were performed by modifying the residual functions and a few input parameters in the {doc}`Blasius sample program <stable:examples/cxx/blasius>` to find solutions to arbitrary sets of equations at a single point, rather than along a 1-D array of points. -### Implementing the Simple Solver +## Implementing the Simple Solver -My first development objective was to create a basic standalone solver for the well-stirred reactor model. As mentioned previously, solutions for this type of problem are characterized by a [set of nonlinear equations](https://drive.google.com/file/d/1vxt3tW1wbvMLTaDygRmpqEJN6yNSO_Lv/view?usp=sharing) that are typically solved by some numerical analysis software, in this case the one that’s built in to Cantera. The Blasius sample code worked well for my initial tests, so I based the structure of my solver on this program, even directly using the simplified [boundary value problem interface](https://github.com/Cantera/cantera/blob/main/samples/cxx/bvp/BoundaryValueProblem.h) to Cantera’s solver. Unfortunately, I couldn’t get this to converge to an appropriate solution. Even given the true solution as an initial vector, the slightest of inaccuracies in inputted properties seemed to result in huge residual values of the energy equation, pushing the solver further from an acceptable solution with each iteration. After doing some research on why this might be, I found that it’s likely due to the exponential dependence of reaction rates on temperature, which makes convergence of the 0-D steady-state equation system quite difficult for a numerical solver. There are a few potential solutions to the issue, which I’m planning on studying in more detail in the coming weeks to get this version of the solver working: +My first development objective was to create a basic standalone solver for the well-stirred reactor model. As mentioned previously, solutions for this type of problem are characterized by a [set of nonlinear equations](https://drive.google.com/file/d/1vxt3tW1wbvMLTaDygRmpqEJN6yNSO_Lv/view?usp=sharing) that are typically solved by some numerical analysis software, in this case the one that’s built in to Cantera. The Blasius sample code worked well for my initial tests, so I based the structure of my solver on this program, even directly using the simplified {doc}`boundary value problem interface <stable:examples/cxx/BoundaryValueProblem>` to Cantera’s solver. Unfortunately, I couldn’t get this to converge to an appropriate solution. Even given the true solution as an initial vector, the slightest of inaccuracies in inputted properties seemed to result in huge residual values of the energy equation, pushing the solver further from an acceptable solution with each iteration. After doing some research on why this might be, I found that it’s likely due to the exponential dependence of reaction rates on temperature, which makes convergence of the 0-D steady-state equation system quite difficult for a numerical solver. There are a few potential solutions to the issue, which I’m planning on studying in more detail in the coming weeks to get this version of the solver working: - The energy equation in the model may need to be replaced with one that considers transient properties - The system may need to be solved twice, first at a fixed temperature (without the energy equation) to obtain a “consistent” initial guess for a second run which will solve for the true solution @@ -30,14 +26,8 @@ My first development objective was to create a basic standalone solver for the w - A more advanced, problem-specific version of the Cantera solver may need to be used rather than the simplified boundary value problem interface - Something else? -### PSR Solver v0.1 +## PSR Solver v0.1 After some brief experimentation with the ideas listed above, I noticed that the well-stirred reactor equations converged very quickly to the correct solution when simulated at arbitrarily fixed temperatures. This confirmed my suspicion that the addition of the energy equation to the system was causing the trouble. At its roots, the energy equation ensures energy conservation through the reactor by forcing the total enthalpy of the exhaust gas mixture at the reactor outlet to match the total enthalpy of the gas mixture at the inlet. The total enthalpy of the exhaust is directly correlated to reactor temperature, which is typically the property that a numerical solver will adjust in attempt to satisfy the energy equation. I realized that Cantera may provide an alternate way to satisfy the conservation of energy, by keeping total enthalpy fixed via the `setState_HP()` method of the thermodynamics library. After specifying iteration mass fractions, exhaust enthalpy can be forced to match the inlet enthalpy simply by explicitly setting it this way with `setState_HP()`. This function will adjust any dependent properties, like temperature, as needed in order to satisfy the laws of thermodynamics. This idea evolved into [my first working version](https://github.com/paulblum/cantera/blob/0DSS/samples/cxx/psr/PSRv1.cpp) of a PSR solver! This experimental version of the solver converges quickly for simple reactions, but has trouble finding solutions to more complicated ones. At this point, I’m not entirely sure of the extent of v0.1’s capabilities, but it will be tested thoroughly in the coming weeks and used in the future as seen fit. - -### Keep Reading: - -Next Post - [GSoC 2020 Blog Post 2](https://cantera.org/blog/gsoc-2020-blog-2) - -Start from the Beginning - [Introduction](https://cantera.org/blog/gsoc-2020-intro) diff --git a/posts/gsoc-2020-blog-2.md b/source/news/gsoc-2020-blog-2.md similarity index 79% rename from posts/gsoc-2020-blog-2.md rename to source/news/gsoc-2020-blog-2.md index e0c5bb3a9..d6e193226 100644 --- a/posts/gsoc-2020-blog-2.md +++ b/source/news/gsoc-2020-blog-2.md @@ -1,43 +1,32 @@ --- -title: GSoC 2020 Blog Post 2 -date: 2020-06-29 14:00:00 UTC-04:00 -slug: gsoc-2020-blog-2 +date: 2020-06-29 14:00 tags: GSoC 2020 -description: A recap of work during weeks 3 & 4. -type: text author: Paul Blum --- -## _Developing a 0-D Steady-State Combustion Solver for Cantera_ +# GSoC 2020: Developing a 0-D Steady-State Combustion Solver for Cantera My work since last posting has been characterized by research and experimentation, and this blog post will highlight some of the findings that I've made. I have learned a lot about Cantera and combustion over the past two weeks, but more excitingly, I developed a working proof-of-concept 0-D steady-state solver, PSRv0.2! -### The Energy Equation +## The Energy Equation In my last blog post, I discussed the troubles I was having with reaching convergence in systems that included the energy equation, and introduced some ideas I had that might be potential remedies. After doing some research, I found a great resource that addressed these ideas and the numerical solution of perfectly-stirred reactors as a whole. The report provided a new version of the energy equation that considered time-dependent and heat release properties, derived from transient forms of the species conservation and energy balance equations; see the [full report](https://www.researchgate.net/publication/236418395_PSE_a_Fortran_program_for_modeling_well-stirred_reactors) for a detailed derivation. Building off of [PSR v0.1](https://github.com/paulblum/cantera/blob/0DSS/samples/cxx/psr/PSRv1.cpp) (introduced in the last blog post), I created a version of the solver that used the new energy equation in its solution attempt. Unfortunately, this too had trouble converging without a very good initial guess. Even after introducing time integration and solving the fixed-temperature problem first, the severe nonlinearities of the solution model almost always made convergence impossible. -### Time Integration +## Time Integration As just hinted at, the solvers that I developed and discussed in my last blog post hadn't been using time integration! I originally thought that this feature of the Cantera solver worked using only the residual function, but this wasn't the case. Time integration is actually done via the backward Euler method. In Cantera's application, the solution at the previous timestep is obtained using the solver's built-in `prevSoln()` method, and the timestep value *dt* is incorporated using its passed-in reciprocal, `rdt`. Each iteration of the backward Euler method needs to be subtracted from the result of the residual function at the corresponding solution vector—the Cantera solver is set up to extract the information that it needs from this difference. Further, modifying values in the `diag` pointer is also required at each iteration. `diag` can be thought of as a mask, and in order to activate time stepping for a specific solution component, its corresponding mask entry needs to be set to 1. - -### PSR Solver v0.2 -Although time integration didn't help convergence with the energy equation, it was exactly what I needed to get PSR v0.1 working! Adding time integration resulted in a capable and accurate PSR solver. I compared this new version of the solver to Cantera's `IdealGasReactor` based on the example code in [combustor.py](https://cantera.org/examples/python/reactors/combustor.py.html), and the results were just about *exactly* the same: +## PSR Solver v0.2 -![](/images/gsoc-2020/v0-2-results.png) +Although time integration didn't help convergence with the energy equation, it was exactly what I needed to get PSR v0.1 working! Adding time integration resulted in a capable and accurate PSR solver. I compared this new version of the solver to Cantera's `IdealGasReactor` based on the example code in {doc}`combustor.py <stable:examples/python/reactors/combustor>`, and the results were just about *exactly* the same: -Check out the full code for [PSR v0.2 on GitHub](https://github.com/paulblum/cantera/blob/0DSS/samples/cxx/psr/PSRv2.cpp)! The energy equation and fixed-temperature versions of the solver are built in for reference, although they weren't used to produce the results above. - -As always, I appreciate any suggestions or feedback you might have. Feel free to leave a comment on this project's page in the [Cantera enhancements repository](https://github.com/Cantera/enhancements/issues/31), or email me at paul_d_blum@yahoo.com. - -Until next time, +```{image} /_static/images/gsoc-2020/v0-2-results.png +``` -@paulblum - -### Keep Reading: +Check out the full code for [PSR v0.2 on GitHub](https://github.com/paulblum/cantera/blob/0DSS/samples/cxx/psr/PSRv2.cpp)! The energy equation and fixed-temperature versions of the solver are built in for reference, although they weren't used to produce the results above. -Next Post - [GSoC 2020 Blog Post 3](https://cantera.org/blog/gsoc-2020-blog-3) +As always, I appreciate any suggestions or feedback you might have. Feel free to leave a comment on this project's page in the [Cantera enhancements repository](https://github.com/Cantera/enhancements/issues/31), or email me at <paul_d_blum@yahoo.com>. -Previous Post - [GSoC 2020 Blog Post 1](https://cantera.org/blog/gsoc-2020-blog-1) +Until next time, -Start from the Beginning - [Introduction](https://cantera.org/blog/gsoc-2020-intro) +[@paulblum](https://github.com/paulblum/) diff --git a/posts/gsoc-2020-blog-3.md b/source/news/gsoc-2020-blog-3.md similarity index 84% rename from posts/gsoc-2020-blog-3.md rename to source/news/gsoc-2020-blog-3.md index 50e5b9a26..77552c07d 100644 --- a/posts/gsoc-2020-blog-3.md +++ b/source/news/gsoc-2020-blog-3.md @@ -1,19 +1,14 @@ --- -title: GSoC 2020 Blog Post 3 -date: 2020-07-26 16:20:00 UTC-04:00 -slug: gsoc-2020-blog-3 +date: 2020-07-26 16:20 tags: GSoC 2020 -description: Developer-oriented detail about how ReactorNet's time integration methods actually work. -type: text author: Paul Blum --- -## _How Does Cantera's Reactor Network Time Integration Feature Work?_ +# GSoC 2020: How Does Cantera's Reactor Network Time Integration Feature Work? -There's a great description of the science behind Cantera's reactor network simulation capabilities available on the Cantera website, [here](https://cantera.org/science/reactors/reactors.html). This post will go into more developer-oriented detail about how the last step, `ReactorNet`'s [time integration methods](https://cantera.org/science/reactors/reactors.html#time-integration-for-reactor-networks), actually work. A `ReactorNet` object doesn't perform time integration on its own. It generates a system of ODE's based on the combined governing equations of all contained `Reactor`s, which is then passed off to an `Integrator` object for solution. What is an `Integrator`? How does this work? -<!-- TEASER_END --> +There's a great description of the science behind Cantera's reactor network simulation capabilities available on the Cantera website, {doc}`here <stable:reference/reactors/index>`. This post will go into more developer-oriented detail about how the last step, `ReactorNet`'s {doc}`time integration methods <stable:develop/reactor-integration>`, actually work. A `ReactorNet` object doesn't perform time integration on its own. It generates a system of ODE's based on the combined governing equations of all contained `Reactor`s, which is then passed off to an `Integrator` object for solution. What is an `Integrator`? How does this work? -### Reactor Network Time Integration, Explained. +## Reactor Network Time Integration, Explained First, let's take a look at a basic example to see how we might utilize Cantera's time integration functionality. We'll simulate an isolated reactor that is homogeneously filled by a gas mixture (the gas state used in this example is arbitrary, but interesting because it's explosive). Then we'll advance the simulation in time to an (arbitrary) absolute time of 1 second, noting the changes in the state of the gas. Follow along by typing this code into an interactive Python interpreter (like [IPython](https://www.codecademy.com/articles/how-to-use-ipython)): @@ -40,20 +35,20 @@ int main() { reac.insert(gas); //fill the reactor with the specified gas ReactorNet sim; //create an empty ReactorNet simulator sim.addReactor(reac); //add the reactor to the ReactorNet - std::cout << gas->thermo()->report(); //print the intitial state of the mixture to the console + std::cout << gas->thermo()->report(); //print the initial state of the mixture to the console sim.advance(1); //advance the simulation to absolute time t = 1 sec std::cout << gas->thermo()->report(); //print the updated state of the mixture to the console return 0; } ``` -For a more advanced example that adds inlets and outlets to the reactor, see Cantera's combustor example ([Python](https://github.com/Cantera/cantera/blob/main/interfaces/cython/cantera/examples/reactors/combustor.py) | [C++](https://github.com/Cantera/cantera/blob/main/samples/cxx/combustor/combustor.cpp)). Additional examples can be found in the [Python Reactor Network Examples](https://cantera.org/examples/python/index.html#python-example-reactors) section of the Cantera website. +For a more advanced example that adds inlets and outlets to the reactor, see Cantera's combustor example ({doc}`Python <stable:examples/python/reactors/combustor>` | {doc}`C++ <stable:examples/cxx/combustor>`). Additional examples can be found in the {doc}`Python Reactor Network Examples <stable:examples/python/reactors/index>` section of the Cantera website. In any case, after properly configuring a reactor network and its components in Cantera, a call to the `ReactorNet`'s `advance()` method can be used to predict the state of the network at a specified time. Transient physical and chemical interactions are simulated by integrating the network's system of ODE governing equations through time, a process that's actually performed by an external `Integrator` object. What is an `Integrator`? The `Integrator` class is Cantera's interface for ODE system integrators. This general-purpose ODE system integration tool can be accessed in any Cantera project by including the **Integrator.h** header file in your code: -- ***Class `Integrator`***: A base class interface for ODE system integrators. ([Documentation](https://cantera.org/documentation/docs-2.4/doxygen/html/d8/d6f/classCantera_1_1Integrator.html)) +- ***Class `Integrator`***: A base class interface for ODE system integrators. (<a href="/2.4/doxygen/html/d8/d6f/classCantera_1_1Integrator.html">Documentation</a>) - Declared and (virtually) implemented in **Integrator.h**, line 52 (see this on [GitHub](https://github.com/Cantera/cantera/blob/cf1c0816e7d535a1fc385063aebb8b8e93a85233/include/cantera/numerics/Integrator.h#L52)) `Integrator` is a *[polymorphic base class](http://www.cplusplus.com/doc/tutorial/polymorphism/)*; it defines a set of *virtual* functionalities that derived classes (the actual ODE system integrators) will provide implementations for. This is done so that different types of `Integrator`s can be used interchangeably, without having to modify their references in code. Method implementations in *different* `Integrator` subclasses can be executed using *the same* call to the `Integrator` base class's `virtual` function—the base class will refer the call to the appropriate subclass implementation, based on the `Integrator` object's type. How do you set the type of an `Integrator`? @@ -65,11 +60,11 @@ Conveniently, **Integrator.h** provides `newIntegrator()`, a *[factory method](h - Declared in **Integrator.h**, line 237 (see this on [GitHub](https://github.com/Cantera/cantera/blob/cf1c0816e7d535a1fc385063aebb8b8e93a85233/include/cantera/numerics/Integrator.h#L237)) - Implemented in **ODE_integrators.cpp**, line 13 (see this on [GitHub](https://github.com/Cantera/cantera/blob/cf1c0816e7d535a1fc385063aebb8b8e93a85233/src/numerics/ODE_integrators.cpp#L13)) -The header files of different `Integrator` implementations are included near the top of **ODE_integrators.cpp** (see this on [GitHub](https://github.com/Cantera/cantera/blob/cf1c0816e7d535a1fc385063aebb8b8e93a85233/src/numerics/ODE_integrators.cpp#L8)). Cantera only includes one type of `Integrator` by default, the `CVODES` ODE solver, which automatically installs alongside Cantera. `CVODES` is an externally developed and maintained solver, a part of @LLNL's SUNDIALS library. If you're interested in learning more specific details about how `CVODES` actually solves an ODE system, I recommend that you read through the [`CVODES` User Guide](https://computing.llnl.gov/sites/default/files/public/cvs_guide.pdf) for detailed documentation and explanation of the module. Note that `ReactorNet` configures `CVODES` to solve via Backward Differentiation Formulas (see [`CVODES` User Guide](https://computing.llnl.gov/sites/default/files/public/cvs_guide.pdf), section 2.1), based on linear system solutions provided by the SUNDIALS `SUNLinSol_LapackDense` module (see [`CVODES` User Guide](https://computing.llnl.gov/sites/default/files/public/cvs_guide.pdf), section 10.7). +The header files of different `Integrator` implementations are included near the top of **ODE_integrators.cpp** (see this on [GitHub](https://github.com/Cantera/cantera/blob/cf1c0816e7d535a1fc385063aebb8b8e93a85233/src/numerics/ODE_integrators.cpp#L8)). Cantera only includes one type of `Integrator` by default, the `CVODES` ODE solver, which automatically installs alongside Cantera. `CVODES` is an externally developed and maintained solver, a part of @LLNL's SUNDIALS library. If you're interested in learning more specific details about how `CVODES` actually solves an ODE system, I recommend that you read through the [`CVODES` User Guide](https://computing.llnl.gov/sites/default/files/cv_guide-5.7.0.pdf) for detailed documentation and explanation of the module. Note that `ReactorNet` configures `CVODES` to solve via Backward Differentiation Formulas (see [`CVODES` User Guide](https://computing.llnl.gov/sites/default/files/cv_guide-5.7.0.pdf), section 2.1), based on linear system solutions provided by the SUNDIALS `SUNLinSol_LapackDense` module (see [`CVODES` User Guide](https://computing.llnl.gov/sites/default/files/cv_guide-5.7.0.pdf), section 10.7). Because `CVODES` is written in C, the `CVodesIntegrator` C++ wrapper is used to access the solver: -- ***Class `CVodesIntegrator`***: A C++ wrapper class for `CVODES`. ([Documentation](https://cantera.org/documentation/docs-2.4/doxygen/html/d9/d6b/classCantera_1_1CVodesIntegrator.html)) +- ***Class `CVodesIntegrator`***: A C++ wrapper class for `CVODES`. (<a href="/2.4/doxygen/html/d9/d6b/classCantera_1_1CVodesIntegrator.html">Documentation</a>) - Declared in **CVodesIntegrator.h**, line 25 (see this on [GitHub](https://github.com/Cantera/cantera/blob/cf1c0816e7d535a1fc385063aebb8b8e93a85233/include/cantera/numerics/CVodesIntegrator.h#L25)) - Implemented in **CVodesIntegrator.cpp**, line 79 (see this on [GitHub](https://github.com/Cantera/cantera/blob/cf1c0816e7d535a1fc385063aebb8b8e93a85233/src/numerics/CVodesIntegrator.cpp#L79)) - Included in **ODE_integrators.cpp**, line 8 (see this on [GitHub](https://github.com/Cantera/cantera/blob/cf1c0816e7d535a1fc385063aebb8b8e93a85233/src/numerics/ODE_integrators.cpp#L8)) @@ -123,7 +118,7 @@ m_integ->integrate(time); The `CVodesIntegrator` wrapper class will then make the appropriate call to the `CVODES` driver function, `CVode()`: -- ***Method `CVode()`***: Main driver of the `CVODES` package. Integrates over a time interval defined by the user, by calling `cvStep()` to do internal time steps. (*Documentation:* see [`CVODES` User Guide](https://computing.llnl.gov/sites/default/files/public/cvs_guide.pdf), section 4.5.6) +- ***Method `CVode()`***: Main driver of the `CVODES` package. Integrates over a time interval defined by the user, by calling `cvStep()` to do internal time steps. (*Documentation:* see [`CVODES` User Guide](https://computing.llnl.gov/sites/default/files/cv_guide-5.7.0.pdf), section 4.5.6) - `int CVode(void *cvode_mem, realtype tout, N_Vector yout, realtype *tret, int itask)`; - Implemented in **cvodes.c**, line 2771 (see this on [GitHub](https://github.com/LLNL/sundials/blob/887af4374af2271db9310d31eaa9b5aeff49e829/src/cvodes/cvodes.c#L2771)) @@ -139,11 +134,11 @@ There are some interesting things to note about this call to `CVode()`: - After execution, `m_y` will contain the computed solution vector, and will later be used to update the `ReactorNet` to its time-integrated state . - The `CV_NORMAL` option tells the solver that it should continue taking internal timesteps until it has reached user-specified `tout` (or just passed it, in which case solutions are reached by interpolation). This provides the appropriate functionality for `ReactorNet::advance()`. The alternate option, `CV_ONE_STEP`, tells the solver to take a single internal step, and is used in `ReactorNet::step()`. -How does `CVODES` know what ODE system it should be solving? The ODE system was actually already specified using `CVodeInit()`, one of the methods automatically invoked during the `ReactorNet::initialize()` routine. `CVODES` requires that its user provide a C function that defines their ODE, able to compute the right-hand side of the ODE system (d`y`/d`t`) for a given value of the independent variable, `t`, and the state vector, `y`. For more information about ODE right-hand side function requirements, see [`CVODES` User Guide](https://computing.llnl.gov/sites/default/files/public/cvs_guide.pdf), section 4.6.1. +How does `CVODES` know what ODE system it should be solving? The ODE system was actually already specified using `CVodeInit()`, one of the methods automatically invoked during the `ReactorNet::initialize()` routine. `CVODES` requires that its user provide a C function that defines their ODE, able to compute the right-hand side of the ODE system (d`y`/d`t`) for a given value of the independent variable, `t`, and the state vector, `y`. For more information about ODE right-hand side function requirements, see [`CVODES` User Guide](https://computing.llnl.gov/sites/default/files/cv_guide-5.7.0.pdf), section 4.6.1. The `CVodesIntegrator` wrapper class provides a useful C++ interface for configuring this C function by pairing with `FuncEval`, an abstract base class for ODE right-hand-side function evaluators. Like the `Integrator` base class, `FuncEval` defines virtual functions that derived classes will provide the implementations for. In this case, classes derived from `FuncEval` will implement the actual evaluation of their particular ODE system. -- ***Class `FuncEval`***: An abstract base class for ODE right-hand-side function evaluators. ([Documentation](https://cantera.org/documentation/docs-2.4/doxygen/html/d1/dd1/classCantera_1_1FuncEval.html)) +- ***Class `FuncEval`***: An abstract base class for ODE right-hand-side function evaluators. (<a href="/2.4/doxygen/html/d1/dd1/classCantera_1_1FuncEval.html">Documentation</a>) - Declared in **FuncEval.h**, line 26 (see this on [GitHub](https://github.com/Cantera/cantera/blob/cf1c0816e7d535a1fc385063aebb8b8e93a85233/include/cantera/numerics/FuncEval.h#L26)) - Implemented in **FuncEval.cpp**, line 7 (see this on [GitHub](https://github.com/Cantera/cantera/blob/cf1c0816e7d535a1fc385063aebb8b8e93a85233/src/numerics/FuncEval.cpp#L7)) @@ -208,16 +203,8 @@ void ReactorNet::eval(doublereal t, doublereal* y, doublereal* ydot, doublereal* } ``` -`ReactorNet`'s `eval()` method invokes calls to `Reactor::evalEqs()`, to evaluate the governing equations of all `Reactor`s contained in the network. This brings us right back to where we started; for more information see Cantera's [reactor network science page](https://cantera.org/science/reactors/reactors.html#governing-equations-for-single-reactors). +`ReactorNet`'s `eval()` method invokes calls to `Reactor::evalEqs()`, to evaluate the governing equations of all `Reactor`s contained in the network. This brings us right back to where we started; for more information see Cantera's {doc}`reactor network science page <stable:reference/reactors/index>`. -Hope you enjoyed the post. +Hope you enjoyed the post. -@paulblum - -### Keep Reading: - -Next Post - [GSoC 2020 Blog Post 4](https://cantera.org/blog/gsoc-2020-blog-4) - -Previous Post - [GSoC 2020 Blog Post 2](https://cantera.org/blog/gsoc-2020-blog-2) - -Start from the Beginning - [Introduction](https://cantera.org/blog/gsoc-2020-intro) +[@paulblum](https://github.com/paulblum/) diff --git a/posts/gsoc-2020-blog-4.md b/source/news/gsoc-2020-blog-4.md similarity index 67% rename from posts/gsoc-2020-blog-4.md rename to source/news/gsoc-2020-blog-4.md index ee4414ae4..28ceabb85 100644 --- a/posts/gsoc-2020-blog-4.md +++ b/source/news/gsoc-2020-blog-4.md @@ -1,26 +1,25 @@ --- -title: GSoC 2020 Blog Post 4 -date: 2020-08-18 16:20:00 UTC-04:00 -slug: gsoc-2020-blog-4 +date: 2020-08-18 16:20 tags: GSoC 2020 -description: A description of the 0D steady-state solution method. -type: text author: Paul Blum --- -This summer I've been working to add a dedicated steady-state solver to Cantera's `ZeroD` reactor network simulation module. Inspired by my study of `ZeroD`'s current ODE time-integration solver, `CVodesIntegrator` (see [this post](https://cantera.org/blog/gsoc-2020-blog-3)), I developed a nonlinear algebraic solver class called `Cantera_NonLinSol` to be used by `ReactorNet` to solve the steady-state problem: +# GSoC 2020: A description of the 0D steady-state solution method -- ***Class `Cantera_NonLinSol`***: A nonlinear algebraic system solver, built upon Cantera's 1D multi-domain damped newton solver as a simplified interface. - - Implemented in **Cantera_NonLinSol.h** (see this on [GitHub](https://github.com/paulblum/cantera/blob/ca36e253bd28c6d507eace5b6f1199cac64d8909/include/cantera/numerics/Cantera_NonLinSol.h)) +This summer I've been working to add a dedicated steady-state solver to Cantera's `ZeroD` reactor network simulation module. Inspired by my study of `ZeroD`'s current ODE time-integration solver, `CVodesIntegrator` (see {ref}`this post <gsoc-2020-blog-3>`), I developed a nonlinear algebraic solver class called `Cantera_NonLinSol` to be used by `ReactorNet` to solve the steady-state problem: + +- **Class `Cantera_NonLinSol`**: A nonlinear algebraic system solver, built upon Cantera's 1D multi-domain damped newton solver as a simplified interface. + - Implemented in `Cantera_NonLinSol.h` (see this on [GitHub](https://github.com/paulblum/cantera/blob/ca36e253bd28c6d507eace5b6f1199cac64d8909/include/cantera/numerics/Cantera_NonLinSol.h)) This blog post will go into detail about the mathematical theory behind solving steady-state reactor systems, and how `Cantera_NonLinSol` can be used to facilitate the process. -<!-- TEASER_END --> -## _Steady-State Solution in `ReactorNet` Simulations_ +## Steady-State Solution in `ReactorNet` Simulations -Steady-state is reached in a reactor when all internal state variables become constant while time advances, as different internal processes that would normally change these variables become perfectly balanced with each other. The governing equations discussed on Cantera’s [Reactor Science](https://cantera.org/science/reactors.html) page will still dictate the physical properties of the system, but their time derivatives become zero as properties become steady. This means that the governing equations, normally a system of ordinary differential equations, can be reduced to a system of nonlinear algebraic equations: +Steady-state is reached in a reactor when all internal state variables become constant while time advances, as different internal processes that would normally change these variables become perfectly balanced with each other. The governing equations discussed on Cantera’s {doc}`stable:reference/reactors/index` page will still dictate the physical properties of the system, but their time derivatives become zero as properties become steady. This means that the governing equations, normally a system of ordinary differential equations, can be reduced to a system of nonlinear algebraic equations: -{{% thumbnail "/images/gsoc-2020/steady-state-eqs.png" align="center" %}} +```{image} /_static/images/gsoc-2020/steady-state-eqs.png +:align: center +``` The system can now be solved with a nonlinear algebraic solver, which finds solution values for the state variables that will satisfy the system of equations. This means finding the zeroes to the functions defined on the right-hand-side of each equation. This is standard practice for any algebraic solution, and as such, nonlinear algebraic solvers typically require users to input a *residual function* that evaluates a specific system's right-hand-side functions. @@ -28,40 +27,40 @@ Cantera has a built-in damped Newton/time-stepping hybrid solver, defined in the What follows is a general outline of how to use this solver, with specific implementation examples included from my work in `ZeroD`: -#### *Include the `Cantera_NonLinSol.h` header in your code.* +### Include the `Cantera_NonLinSol.h` header in your code. -**ReactorNet.h**, line 12 (see this on [GitHub](https://github.com/paulblum/cantera/blob/ca36e253bd28c6d507eace5b6f1199cac64d8909/include/cantera/zeroD/ReactorNet.h#L12)) +`ReactorNet.h`, line 12 (see this on [GitHub](https://github.com/paulblum/cantera/blob/ca36e253bd28c6d507eace5b6f1199cac64d8909/include/cantera/zeroD/ReactorNet.h#L12)) ```c++ #include "cantera/numerics/Cantera_NonLinSol.h" ``` -#### *Derive a class from `Cantera_NonLinSol` to inherit nonlinear algebraic solution capabilities and define your specific problem.* +### Derive a class from `Cantera_NonLinSol` to inherit nonlinear algebraic solution capabilities and define your specific problem. -**ReactorNet.h**, line 24 (see this on [GitHub](https://github.com/paulblum/cantera/blob/ca36e253bd28c6d507eace5b6f1199cac64d8909/include/cantera/zeroD/ReactorNet.h#L24)) +`ReactorNet.h`, line 24 (see this on [GitHub](https://github.com/paulblum/cantera/blob/ca36e253bd28c6d507eace5b6f1199cac64d8909/include/cantera/zeroD/ReactorNet.h#L24)) ```c++ class ReactorNet : public FuncEval, public Cantera_NonLinSol ``` -`ReactorNet` now exhibits *multiple inheritance*, since it was already a child of class `FuncEval`. The `FuncEval` parent class is used by `Integrator` during ODE time-integration, and its inheritance makes `ReactorNet` an *ODE right-hand-side evaluator*. (Confused? See my [last blog post](https://cantera.org/blog/gsoc-2020-blog-3)!) +`ReactorNet` now exhibits *multiple inheritance*, since it was already a child of class `FuncEval`. The `FuncEval` parent class is used by `Integrator` during ODE time-integration, and its inheritance makes `ReactorNet` an *ODE right-hand-side evaluator*. (Confused? See my {ref}`last blog post <gsoc-2020-blog-3>`!) *Notice that the existing time-integration solver, `Integrator`, is not a parent class to `ReactorNet`.* `Integrator` is an external solver object that uses user-defined functions from *another* class, `FuncEval`. This requires the inclusion of two headers, explicit construction of an external object, and the passing of the `this` pointer to locate user definitions: -**ReactorNet.h**, lines 10-11 (see this on [GitHub](https://github.com/paulblum/cantera/blob/ca36e253bd28c6d507eace5b6f1199cac64d8909/include/cantera/zeroD/ReactorNet.h#L10)) +`ReactorNet.h`, lines 10-11 (see this on [GitHub](https://github.com/paulblum/cantera/blob/ca36e253bd28c6d507eace5b6f1199cac64d8909/include/cantera/zeroD/ReactorNet.h#L10)) ```c++ #include "cantera/numerics/FuncEval.h" #include "cantera/numerics/Integrator.h" ``` -**ReactorNet.cpp**, line 18 (see this on [GitHub](https://github.com/paulblum/cantera/blob/ca36e253bd28c6d507eace5b6f1199cac64d8909/src/zeroD/ReactorNet.cpp#L18)) +`ReactorNet.cpp`, line 18 (see this on [GitHub](https://github.com/paulblum/cantera/blob/ca36e253bd28c6d507eace5b6f1199cac64d8909/src/zeroD/ReactorNet.cpp#L18)) ```c++ m_integ(newIntegrator("CVODE")), ``` -**ReactorNet.cpp**, line 112 (see this on [GitHub](https://github.com/paulblum/cantera/blob/ca36e253bd28c6d507eace5b6f1199cac64d8909/src/zeroD/ReactorNet.cpp#L112)) +`ReactorNet.cpp`, line 112 (see this on [GitHub](https://github.com/paulblum/cantera/blob/ca36e253bd28c6d507eace5b6f1199cac64d8909/src/zeroD/ReactorNet.cpp#L112)) ```c++ m_integ->initialize(m_time, *this); @@ -69,15 +68,17 @@ m_integ->initialize(m_time, *this); In contrast, `Cantera_NonLinSol` is written as an abstract base class that provides nonlinear algebraic solution capability to its children. User-defined function implementations are provided by *overriding* pure virtual functions declared in the parent class. `Cantera_NonLinSol` requires a single header inclusion, is automatically constructed by the child class, and can call user-provided functions without the use of a pointer. -#### *Implement the problem-specific user-defined functions, to provide the solver with the number of equations (`ctNLS_nEqs()`), initial values (`ctNLS_initialValue()`), and residual function (`ctNLS_residFunction()`).* +### Implement the problem-specific user-defined functions, to provide the solver with the number of equations (`ctNLS_nEqs()`), initial values (`ctNLS_initialValue()`), and residual function (`ctNLS_residFunction()`). Steady-state solution is implemented using the same solution vector as in the transient case. This vector is a concatenation of solution vectors for each reactor in the network, with each sub-vector having the following format: -{{% thumbnail "/images/gsoc-2020/sol-vector.png" align="center" %}} +```{image} /_static/images/gsoc-2020/sol-vector.png +:align: center +``` The size, `m_nv`, of the overall network solution vector is determined during `ReactorNet` initialization, and is returned by `ctNLS_nEqs()`: -**ReactorNet.cpp**, lines 371-377 (see this on [GitHub](https://github.com/paulblum/cantera/blob/ca36e253bd28c6d507eace5b6f1199cac64d8909/src/zeroD/ReactorNet.cpp#L371)) +`ReactorNet.cpp`, lines 371-377 (see this on [GitHub](https://github.com/paulblum/cantera/blob/ca36e253bd28c6d507eace5b6f1199cac64d8909/src/zeroD/ReactorNet.cpp#L371)) ```c++ m_nv = 0; @@ -89,7 +90,7 @@ for (size_t n = 0; n < m_reactors.size(); n++) { } ``` -**ReactorNet.cpp**, lines 397-400 (see this on [GitHub](https://github.com/paulblum/cantera/blob/ca36e253bd28c6d507eace5b6f1199cac64d8909/src/zeroD/ReactorNet.cpp#L397)) +`ReactorNet.cpp`, lines 397-400 (see this on [GitHub](https://github.com/paulblum/cantera/blob/ca36e253bd28c6d507eace5b6f1199cac64d8909/src/zeroD/ReactorNet.cpp#L397)) ```c++ size_t ReactorNet::ctNLS_nEqs() @@ -102,7 +103,7 @@ Numerical solution of the steady-state equations is an initial-value problem, an In the source code, `ReactorNet::ctNLS_initialValue()` calls the `initialValue()` method of the appropriate `Reactor`, which returns the initial value of the requested solution component: -**ReactorNet.cpp**, lines 382-388 (see this on [GitHub](https://github.com/paulblum/cantera/blob/ca36e253bd28c6d507eace5b6f1199cac64d8909/src/zeroD/ReactorNet.cpp#L382)) +`ReactorNet.cpp`, lines 382-388 (see this on [GitHub](https://github.com/paulblum/cantera/blob/ca36e253bd28c6d507eace5b6f1199cac64d8909/src/zeroD/ReactorNet.cpp#L382)) ```c++ doublereal ReactorNet::ctNLS_initialValue(size_t i) @@ -114,7 +115,7 @@ doublereal ReactorNet::ctNLS_initialValue(size_t i) } ``` -**Reactor.cpp**, lines 547-559 (see this on [GitHub](https://github.com/paulblum/cantera/blob/ca36e253bd28c6d507eace5b6f1199cac64d8909/src/zeroD/Reactor.cpp#L547)) +`Reactor.cpp`, lines 547-559 (see this on [GitHub](https://github.com/paulblum/cantera/blob/ca36e253bd28c6d507eace5b6f1199cac64d8909/src/zeroD/Reactor.cpp#L547)) ```c++ doublereal Reactor::initialValue(size_t i) { @@ -141,7 +142,7 @@ Lastly, the residual function that defines the specific nonlinear algebraic syst These assumptions allow updating a `Reactor`'s internal state based on the known pressure and specific enthalpy, along with the iteration mass fractions computed by the solver. Residuals for mass, volume, and energy are set based on corresponding values in the updated reactor, while species conservation residuals are calculated using the built-in `evalEqs()` method: -**Reactor.cpp**, lines 500-543 (see this on [GitHub](https://github.com/paulblum/cantera/blob/ca36e253bd28c6d507eace5b6f1199cac64d8909/src/zeroD/Reactor.cpp#L500)) +`Reactor.cpp`, lines 500-543 (see this on [GitHub](https://github.com/paulblum/cantera/blob/ca36e253bd28c6d507eace5b6f1199cac64d8909/src/zeroD/Reactor.cpp#L500)) ```c++ void Reactor::residFunction(double *sol, double *rsd) @@ -166,9 +167,9 @@ void Reactor::residFunction(double *sol, double *rsd) } ``` -#### *Call the inherited `solve()` function, which will update the network to its steady-state.* +### Call the inherited `solve()` function, which will update the network to its steady-state. -**ReactorNet.cpp**, line 379 (see this on [GitHub](https://github.com/paulblum/cantera/blob/ca36e253bd28c6d507eace5b6f1199cac64d8909/src/zeroD/ReactorNet.cpp#L379)) +`ReactorNet.cpp`, line 379 (see this on [GitHub](https://github.com/paulblum/cantera/blob/ca36e253bd28c6d507eace5b6f1199cac64d8909/src/zeroD/ReactorNet.cpp#L379)) ```c++ Cantera_NonLinSol::solve(); @@ -176,16 +177,8 @@ Cantera_NonLinSol::solve(); Note that the `Cantera_NonLinSol` namespace is included in this call only for clarity. -This solver is still in its initial development phase, and feedback or suggestions you may be able to provide would definitely contribute to its success! Leave me a comment on [GitHub](https://github.com/Cantera/enhancements/issues/31), the [Cantera User's Group](https://groups.google.com/g/cantera-users), or email me at paul_d_blum@yahoo.com. +This solver is still in its initial development phase, and feedback or suggestions you may be able to provide would definitely contribute to its success! Leave me a comment on [GitHub](https://github.com/Cantera/enhancements/issues/31), the [Cantera User's Group](https://groups.google.com/g/cantera-users), or email me at <paul_d_blum@yahoo.com>. Thanks for reading! -@paulblum - -### Keep Reading: - -Next Post - [GSoC 2020 Project Summary](https://cantera.org/blog/gsoc-2020-final) - -Previous Post - [GSoC 2020 Blog Post 3](https://cantera.org/blog/gsoc-2020-blog-3) - -Start from the Beginning - [Introduction](https://cantera.org/blog/gsoc-2020-intro) +[@paulblum](https://github.com/paulblum/) diff --git a/posts/gsoc-2020-final.md b/source/news/gsoc-2020-final.md similarity index 85% rename from posts/gsoc-2020-final.md rename to source/news/gsoc-2020-final.md index be9012d66..1cfd5828a 100644 --- a/posts/gsoc-2020-final.md +++ b/source/news/gsoc-2020-final.md @@ -1,44 +1,39 @@ --- -title: GSoC 2020 Project Summary -date: 2020-08-31 16:20:00 UTC-04:00 -slug: gsoc-2020-final +date: 2020-08-31 16:20 tags: GSoC 2020 -description: A summary of the progress made during GSoC 2020 towards a Cantera 0-D steady-state combustion solver. -type: text author: Paul Blum --- -## Google Summer of Code 2020: *Developing a 0-D Steady-State Combustion Solver for Cantera* +# GSoC 2020: Developing a 0-D Steady-State Combustion Solver for Cantera Combustion is a fundamental discipline of modern science, and understanding it has enabled the development of our technologies in electricity production, heating, transportation, and industry. Advancements in combustion science have been facilitated by our ability to simulate the phenomenon, made possible by computer software like Cantera. The goal of this project was to add a new solver to Cantera that would allow users to directly simulate zero-dimensional steady-state combustion, which can occur in reactors when internal chemical processes become perfectly balanced with one another. This type of idealized simulation can be used to quickly and accurately approximate the behavior of real combustion systems. -<!-- TEASER_END --> -- [Introductory Blog Post](https://cantera.org/blog/gsoc-2020-intro) +- {ref}`Introductory Blog Post <gsoc-2020-intro>` - [Full Project Proposal](https://drive.google.com/file/d/1vaOjydm6wWKgF2M4J3iFwNZNKHX5laBY/view) - [Official GSoC Project Link](https://summerofcode.withgoogle.com/projects/#4550970131873792) As the project began, discussions with the Cantera community led me to make a few deviations from the project proposal, switching the development language to C++ and the numerical solver to Cantera’s built-in 1D multi-domain damped Newton solver. These changes allowed me to build upon existing Cantera C++ examples to create a simple constant-pressure perfectly-stirred reactor simulator, PSRv0.1. This initial version of the simulation tool could find solutions only to systems with simple reactions, but it was invaluable in helping me understand how the Cantera solver worked and how I would need to implement the governing equations in future versions. -- [Blog Post 1: Learning C++, Switching Solvers, and Initial Implementations](https://cantera.org/blog/gsoc-2020-blog-1) +- {ref}`Blog Post 1: Learning C++, Switching Solvers, and Initial Implementations <gsoc-2020-blog-1>` - [PSRv0.1 Code](https://github.com/paulblum/cantera/blob/0DSS/samples/cxx/psr/PSRv1.cpp) Improving PSRv0.1 required extensive research on existing implementations of perfectly-stirred reactor solvers, and experimentation with different mathematical models of the governing equations. A simplification of these equations and the incorporation of time-stepping to improve convergence intervals led to the development of PSRv0.2, an accurate and broadly-capable version of the simulator. -- [Blog Post 2: Developing a Capable and Accurate PSR Solver](https://cantera.org/blog/gsoc-2020-blog-2) +- {ref}`Blog Post 2: Developing a Capable and Accurate PSR Solver <gsoc-2020-blog-2>` - [PSRv0.2 Code](https://github.com/paulblum/cantera/blob/0DSS/samples/cxx/psr/PSRv2.cpp) With a working proof-of-concept simulator, the next step was to introduce compatibility with Cantera’s existing reactor network module, which would need to provide initial conditions and reactor-specific governing equations to the steady-state solver. Documentation at this implementation depth of Cantera’s source code was limited; becoming familiar with it required a detailed study of the code with line-by-line walkthroughs of a few example simulations. To better my own understanding and share what I had learned with the Cantera community, I wrote a developer-oriented overview of the module’s implementation, and created a new C++ example problem that uses the module’s fundamental solution tools to solve the governing equations that I had been working on. Based on the external-solver usage in Cantera’s reactor network module, I created a dedicated nonlinear algebraic solver interface, `Cantera_NonLinSol`, to be used by the reactor network module to simulate steady-state systems. Usage of this interface is demonstrated in PSRv0.3. -- [Blog Post 3: How Does Cantera’s Reactor Network Time Integration Feature Work?](https://cantera.org/blog/gsoc-2020-blog-3) +- {ref}`Blog Post 3: How Does Cantera’s Reactor Network Time Integration Feature Work? <gsoc-2020-blog-3>` - [New C++ Example: custom.cpp](https://github.com/Cantera/cantera/pull/922) - [`Cantera_NonLinSol` Interface](https://github.com/paulblum/cantera/blob/ca36e253bd28c6d507eace5b6f1199cac64d8909/include/cantera/numerics/Cantera_NonLinSol.h) - [PSRv0.3 Code](https://github.com/paulblum/cantera/blob/0DSS/samples/cxx/psr/PSRv0-3.cpp) At this point, incorporating steady-state simulation into the reactor network module was relatively straightforward because most of the solution process took place in the external `Cantera_NonLinSol` interface. After including the interface appropriately and providing implementations for problem-specific system-defining pure virtual functions, the reactor network module was ready to simulate 0-D steady-state combustion at constant pressure. Usage of this feature is demonstrated in PSRv0.4, and more detailed information about its implementation and mathematical modeling are provided in my fourth GSoC blog post. -- [Blog Post 4: Steady-State Solution in `ReactorNet` Simulations](https://cantera.org/blog/gsoc-2020-blog-4) +- {ref}`Blog Post 4: Steady-State Solution in ReactorNet Simulations <gsoc-2020-blog-4>` - [PSRv0.4 Code](https://github.com/paulblum/cantera/blob/0DSS/samples/cxx/psr/PSRv0-4.cpp) -The next step in this project’s development is to generalize the governing equations to allow steady-state simulation at variable or unknown reactor pressures. I’ve already begun working on adding this capability, and I’m expecting it to be operational very soon! Future updates will be posted to the Cantera [enhancements repository](https://github.com/Cantera/enhancements/issues/31) on GitHub, so be sure to stay tuned for the release of the finished steady-state solver. +The next step in this project’s development is to generalize the governing equations to allow steady-state simulation at variable or unknown reactor pressures. I’ve already begun working on adding this capability, and I’m expecting it to be operational very soon! Future updates will be posted to the Cantera [enhancements repository](https://github.com/Cantera/enhancements/issues/31) on GitHub, so be sure to stay tuned for the release of the finished steady-state solver. This project has been one of the most challenging that I’ve ever worked on, but ultimately one of the most rewarding. I’ve learned an incredible amount about combustion and open-source programming, and I’m ready to continue using and advancing these skillsets to contribute even more code in the future. I’d like to extend a special thank you to my mentor [@bryanwweber](https://github.com/bryanwweber) for making this experience possible, and for all of the help he provided along the way. diff --git a/posts/gsoc-2020-intro.md b/source/news/gsoc-2020-intro.md similarity index 58% rename from posts/gsoc-2020-intro.md rename to source/news/gsoc-2020-intro.md index 125ead6f2..a107c8fbb 100644 --- a/posts/gsoc-2020-intro.md +++ b/source/news/gsoc-2020-intro.md @@ -1,31 +1,23 @@ --- -title: GSoC 2020 Introduction -date: 2020-06-01 16:20:00 UTC-04:00 -slug: gsoc-2020-intro +date: 2020-06-01 16:20 tags: GSoC 2020 -description: GSoC 2020 has officially begun! -type: text author: Paul Blum --- -# Google Summer of Code 2020 - _Developing a 0-D Steady-State Combustion Solver for Cantera_ +# GSoC 2020 - Developing a 0-D Steady-State Combustion Solver for Cantera -### Introduction +## Introduction -Hello, world! My name is Paul Blum (@paulblum), and I'm an undergraduate student at the University of Connecticut studying Mechanical Engineering and Computer Science & Engineering. I was introduced to Cantera by @bryanwweber, one of my professors at UConn, as an undergraduate research project that might allow me to jointly apply concepts from both of my fields of study. Since then, I’ve completed some small projects for the Cantera software and its website ([Cantera/cantera #709](https://github.com/Cantera/cantera/pull/709), [Cantera/cantera-website #95](https://github.com/Cantera/cantera-website/pull/95), [Cantera/cantera-website #98](https://github.com/Cantera/cantera-website/pull/98)). +Hello, world! My name is Paul Blum ([@paulblum](https://github.com/paulblum)), and I'm an undergraduate student at the University of Connecticut studying Mechanical Engineering and Computer Science & Engineering. I was introduced to Cantera by [@bryanwweber](https://github.com/bryanwweber), one of my professors at UConn, as an undergraduate research project that might allow me to jointly apply concepts from both of my fields of study. Since then, I’ve completed some small projects for the Cantera software and its website ([Cantera/cantera #709](https://github.com/Cantera/cantera/pull/709), [Cantera/cantera-website #95](https://github.com/Cantera/cantera-website/pull/95), [Cantera/cantera-website #98](https://github.com/Cantera/cantera-website/pull/98)). Cantera has presented me with the opportunity to challenge myself, learn an incredible amount, and develop my skills as a scientist and an engineer. With this perception, I am excited to announce that I will be developing code for Cantera full-time this summer as part of Google Summer of Code 2020. -### Project Details +## Project Details Over the next few months, I'll be working to create a fast and efficient 0-D steady-state combustion solver to integrate as a new feature into Cantera. Solvers for this type of idealized combustion are typically used in applications like studying stabilization and extinction in high velocity combustion, investigating the formation of poisonous nitrogen oxides during burning, determining the values of global reaction parameters in analytical models, and approximating more complex systems like gas-turbine combustors. Throughout the summer I'll be posting updates on development progress to the [Cantera blog](https://cantera.org/blog/index.html) and the [Cantera enhancements repository](https://github.com/Cantera/enhancements/issues/31), so be sure to stay tuned! In the meantime, you can read more about this project via the official GSoC [project description](https://summerofcode.withgoogle.com/projects/#4550970131873792), or my more detailed [project proposal](https://drive.google.com/file/d/1vaOjydm6wWKgF2M4J3iFwNZNKHX5laBY/view?usp=sharing). -If you're interested in learning more about this project, or have any questions or suggestions regarding its development, feel free to email me at paul_d_blum@yahoo.com. +If you're interested in learning more about this project, or have any questions or suggestions regarding its development, feel free to email me at <paul_d_blum@yahoo.com>. Looking forward to a great summer! - -### Keep Reading: - -Next Post - [Blog Post 1](https://cantera.org/blog/gsoc-2020-blog-1) diff --git a/posts/kincodecon2018.md b/source/news/kincodecon2018.md similarity index 88% rename from posts/kincodecon2018.md rename to source/news/kincodecon2018.md index f20b17c23..d613d3881 100644 --- a/posts/kincodecon2018.md +++ b/source/news/kincodecon2018.md @@ -1,6 +1,7 @@ --- +blogpost: true title: KinCodeCon 2018 -date: 2018-11-21 14:30:00 UTC-08:00 +date: 2018-11-21 14:30 slug: kincodecon2018 tags: kincodecon, steering-committee description: KinCodeCon 2018 and NumFOCUS SDG @@ -10,13 +11,11 @@ author: Kyle Niemeyer # KinCodeCon 2018 -Thanks to the support of [NumFOCUS] via a +Thanks to the support of [NumFOCUS](https://numfocus.org) via a [small development grant](https://numfocus.org/blog/fall-2018-open-source-development-grants), -the [Cantera Steering Committee](/governance.html#current-steering-committee) met in +the [Cantera Steering Committee](current-steering-committee) met in person on MIT's campus in Cambridge, MA, at the 3rd Annual KinCodeCon on November 16–18, 2018. -<!-- TEASER_END --> - The Steering Committee (SC) met virtually in 2016 and 2017 to discuss issues and plan for the future, and while we tried to include some live code sprinting, the virtual nature of the meetings made this challenging. It was also challenging to block off more than a few hours at a time when @@ -38,11 +37,11 @@ the NumFOCUS umbrella to save on administrative overhead. After lunch, the SC discussed affiliated packages in the Cantera ecosystem. These packages tend to use Cantera in some way, although they are mostly not officially maintained by the -Cantera developers. We have added an {{% doc %}}affiliated-packages{{% /doc %}} page that +Cantera developers. We have added an [](/affiliated) page that lists the current packages the SC is aware of. The list will be "crowd-sourced" with input from the Users' Group on Google. -On Saturday, the SC discussed the governance of the Cantera project. We identified the [Astropy] +On Saturday, the SC discussed the governance of the Cantera project. We identified the [Astropy](http://www.astropy.org) project as an "aspirational peer" project because of their role in the astronomy community. We also identified their governance procedures as robust and relatively transparent, something we would like to strive towards. @@ -95,8 +94,4 @@ individually. Cantera is now officially part of NumFOCUS. NumFOCUS is a 501(c)3 nonprofit dedicated to supporting the open source scientific computing community. If you are interested in learning more about -NumFOCUS, please visit their website at [NumFOCUS], or our website at https://cantera.org/community.html#donations. - -[NumFOCUS]: https://numfocus.org -[Cantera]: https://cantera.org -[Astropy]: http://www.astropy.org +NumFOCUS, please visit their website at [NumFOCUS](https://numfocus.org), or our website at <https://cantera.org/community.html#donations>. diff --git a/source/news/new-website-is-live.md b/source/news/new-website-is-live.md new file mode 100644 index 000000000..66243bff7 --- /dev/null +++ b/source/news/new-website-is-live.md @@ -0,0 +1,57 @@ +--- +date: 2018-07-02 15:02 +author: "Bryan Weber" +category: website +language: English +--- + +# The New Cantera Website is Here! + +This summer, Bryan Weber and Steven DeCaluwe took on the project of revamping the Cantera website. +The old website was, well, old and needed to be refreshed. Thanks to a grant from +[NumFOCUS](https://numfocus.org), Bryan and Steven were able to completely redo the website! + +The main focus of the update was to make it much easier for all users of Cantera to quickly find the +information they need. The older website was a list of links to locations deeper in the website, +which made it hard for new and expert users of Cantera to find the page they were looking for. On +the new website, we have clearly marked sections for new users and advanced users to find what +they're looking for. All of the same content is available, we've just reorganized it and +(hopefully!) made things easier to find. + +:::{card} Old Cantera Website +```{image} /_static/images/new-website-is-live/old-cantera-website.png +:align: center +:width: 100% +``` +::: + +We have a Tutorials section to get new users started with using Cantera, we have a +separate "Science" section that explains some of the basic equations and principles +underlying the models that Cantera uses, and we still have all the API documentation that you need +over in the Documentation section. There is also a Community section with +information about how to reach the Cantera steering community and where our code and discussions +live. + +## NumFOCUS + +This work was sponsored by NumFOCUS through their Small Development Grants program. This program +gives small grants to NumFOCUS sponsored projects to help improve their code or their community. +Cantera was awarded the grant as part of the [Spring 2018 round of funding](https://www.numfocus.org/blog/numfocus-awards-development-grants-to-open-source-projects-spring-2018). If you +are interested in more information about this grant, or future grants, please email the [steering +committee](mailto:steering@cantera.org). More information about [NumFOCUS](https://numfocus.org) can be found in the +Community section of our new website! Thank you NumFOCUS! + +## Nuts and bolts + +The website is now built with the Nikola static site generator and much of the content has been +migrated to a [new repository](https://github.com/Cantera/cantera-website). The allows us to update the website content without +pushing commits to the main Cantera repository and rebuilding all of the documentation. The website +is themed with the [Bootstrap 4](https://getbootstrap.com) theme. The documentation of the Cantera API is still +done with Sphinx and Doxygen in the [main code repository](https://github.com/Cantera/cantera). + +All of the links to the old website structure should be automatically redirected to the equivalent +location in the new structure. If you find any redirects that don't work, or any broken links within +cantera.org, please [file an issue](https://github.com/Cantera/cantera-website/issues/new) on our website repository. + +There are still a few things we're working out with the new site. If you would like to contribute, +check out the [issues page](https://github.com/Cantera/cantera-website/issues) on our repository and leave a comment! diff --git a/posts/nsf-awards-cantera-project-25m-through-2022.md b/source/news/nsf-awards-cantera-project-25m-through-2022.md similarity index 72% rename from posts/nsf-awards-cantera-project-25m-through-2022.md rename to source/news/nsf-awards-cantera-project-25m-through-2022.md index 2eceb67c0..b37cb326e 100644 --- a/posts/nsf-awards-cantera-project-25m-through-2022.md +++ b/source/news/nsf-awards-cantera-project-25m-through-2022.md @@ -1,12 +1,6 @@ --- -title: NSF awards Cantera Project $2.5M through 2022 -slug: nsf-awards-cantera-project-25m-through-2022 -date: '2019-09-09 15:07:07 UTC-04:00' +date: 2019-09-09 15:07 tags: funding -category: null -link: null -description: null -type: text --- # NSF awards Cantera Project $2.5M through 2022 @@ -15,4 +9,4 @@ We are proud to announce that NSF has awarded funds to members of the developmen In particular, new capabilities added to Cantera and outreach to new scientific domains will help recruit new users in fields such as electrochemistry, catalysis, and atmospheric chemistry, while continuing to build the current user base. Helping recruit new users while also making it easier for current users to contribute to the software will help further establish Cantera's status as a powerful, user-friendly, and community-driven software package with high impact in multiple fields. -The [Cantera Steering Committee](https://cantera.org/governance.html#current-steering-committee) is happy to discuss the successful proposal with interested parties. Please email <steering@cantera.org> for more information, or see the [award announcement](https://www.nsf.gov/awardsearch/showAward?AWD_ID=1931584&HistoricalAwards=false). +The [Cantera Steering Committee](current-steering-committee) is happy to discuss the successful proposal with interested parties. Please email <steering@cantera.org> for more information, or see the [award announcement](https://www.nsf.gov/awardsearch/showAward?AWD_ID=1931584&HistoricalAwards=false). diff --git a/themes/cantera/assets/css/custom.css b/themes/cantera/assets/css/custom.css deleted file mode 100644 index ae9f73536..000000000 --- a/themes/cantera/assets/css/custom.css +++ /dev/null @@ -1,61 +0,0 @@ -#logo { width: 250px; } -#cards { padding-bottom: 5%; } -.jumbotron-text { text-align: center; padding-bottom: 16px; font-size: 1.5rem; font-weight: 500; } -.jumbotron { background-color: white; margin-top: 30px; margin-bottom: 48px; padding: 0 0; } -.img-container { text-align: center; } - -a.headerlink { visibility: hidden; padding: 0 4px 0 4px; } -h1:hover > a.headerlink, -h2:hover > a.headerlink, -h3:hover > a.headerlink, -h4:hover > a.headerlink, -h5:hover > a.headerlink, -h6:hover > a.headerlink { - visibility: visible; -} - -.example-header { padding: 20px 0; } -.example-row { padding-bottom: 20px; } - -.tutorials { margin: 40px 0; padding: 0 0 !important; } - -section { margin-top: 20px; margin-bottom: 20px; padding: 0 0; } - -a.docs:hover { background-color: #007994; color: #ffffff; } -a.docs, a.dev-docs, a.release-notes { color: #000000; } -a.dev-docs:hover { background-color: #fd7f03; color: #ffffff; } -a.release-notes:hover { background-color: #c80202; color: #ffffff; } - -.row { margin: 0 0 20px; } - -.docutils.literal { - font-family: SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace; - font-weight: bold; - font-size: 1em; - color: #444; - word-break: break-word; -} - -a > tt { - color: inherit; -} - -.section-card { - font-size: 1.25rem; - font-weight: 500; -} - -.footer li { - display: inline-block; - text-decoration: none; -} -.footer li::after { - content: " |"; -} -.footer li:last-of-type::after { - content: ""; -} -.footer-text { - margin-left: 0; - padding-left: 0; -} diff --git a/themes/cantera/assets/img/favicon.ico b/themes/cantera/assets/img/favicon.ico deleted file mode 100644 index caa70b8e1..000000000 Binary files a/themes/cantera/assets/img/favicon.ico and /dev/null differ diff --git a/themes/cantera/cantera.theme b/themes/cantera/cantera.theme deleted file mode 100644 index 515ccebf2..000000000 --- a/themes/cantera/cantera.theme +++ /dev/null @@ -1,11 +0,0 @@ -[Theme] -engine = jinja -parent = bootstrap4-jinja -author = The Cantera Contributors -author_url = https://cantera.org/ -license = BSD -based_on = Bootstrap 4 <http://getbootstrap.com/> -tags = bootstrap - -[Family] -family = bootstrap4 diff --git a/themes/cantera/templates/base.tmpl b/themes/cantera/templates/base.tmpl deleted file mode 100644 index 25feac149..000000000 --- a/themes/cantera/templates/base.tmpl +++ /dev/null @@ -1,115 +0,0 @@ -{# -*- coding: utf-8 -*- #} -{% import 'base_helper.tmpl' as base with context %} -{% import 'annotation_helper.tmpl' as notes with context %} -{{ set_locale(lang) }} -{{ base.html_headstart() }} -{% block extra_head %} -{# Leave this block alone. #} -{% endblock %} -{{ template_hooks['extra_head']() }} -</head> -<body> -<a href="#content" class="sr-only sr-only-focusable">{{ messages("Skip to main content") }}</a> - -<!-- Menubar --> - -<nav class="navbar navbar-expand-md static-top mb-4 -{% if theme_config.get('navbar_light') %} -navbar-light bg-light -{% else %} -navbar-dark bg-dark -{% endif %} -"> - <div class="container"><!-- This keeps the margins nice --> - <a class="navbar-brand" href="{{ abs_link(_link("root", None, lang)) }}"> - {% if logo_url %} - <img src="{{ logo_url }}" alt="{{ blog_title|e }}" id="logo" class="d-inline-block align-top"> - {% endif %} - - {% if show_blog_title %} - <span id="blog-title">{{ blog_title|e }}</span> - {% endif %} - </a> - <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#bs-navbar" aria-controls="bs-navbar" aria-expanded="false" aria-label="Toggle navigation"> - <span class="navbar-toggler-icon"></span> - </button> - - <div class="collapse navbar-collapse" id="bs-navbar"> - <ul class="navbar-nav ml-auto"> - {{ base.html_navigation_links_entries(navigation_links) }} - {{ template_hooks['menu']() }} - </ul> - {% if search_form %} - {{ search_form }} - {% endif %} - - <ul class="navbar-nav navbar-right"> - {{ base.html_navigation_links_entries(navigation_alt_links) }} - {% block belowtitle %} - {% if translations|length > 1 %} - <li>{{ base.html_translations() }}</li> - {% endif %} - {% endblock %} - {% if show_sourcelink %} - {% block sourcelink %}{% endblock %} - {% endif %} - {{ template_hooks['menu_alt']() }} - </ul> - </div><!-- /.navbar-collapse --> - </div><!-- /.container --> -</nav> - -<!-- End of Menubar --> - -<div class="container" id="content" role="main"> - <div class="body-content"> - <!--Body content--> - {{ template_hooks['page_header']() }} - {% block content %}{% endblock %} - <!--End of body content--> - - <footer id="footer"> - <div class="footer" role="navigation"> - <div class="navbar-text"> - <ul class="footer-text"> - <li><a href="/index.html">Home</a></li> - <li><a href="/community.html#citing-cantera">Citing</a></li> - {% for url, text in navigation_links["en"] %} - <li><a href="{{ url }}">{{ text }}</a></li> - {% endfor %} - </ul> - </div> - <p>{{ content_footer }}</p> - {{ template_hooks['page_footer']() }} - </div> - </footer> - </div> -</div> - -{# {{ base.late_load_js() }} #} - <script src="https://code.jquery.com/jquery-3.5.1.min.js" integrity="sha256-9/aliU8dGd2tb6OSsuzixeV4y/faTqgFtohetphbbj0=" crossorigin="anonymous"></script> - <script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.16.1/umd/popper.min.js" integrity="sha256-/ijcOLwFf26xEYAjW75FizKVo5tnTYiQddPZoLUHHZ8=" crossorigin="anonymous"></script> - <script src="https://stackpath.bootstrapcdn.com/bootstrap/4.5.0/js/bootstrap.min.js" integrity="sha384-OgVRvuATP1z7JjHLkuOU7Xw704+h835Lr+6QL9UvYjZE3Ipu6Tp75j7Bh/kR0JKI" crossorigin="anonymous"></script> - <script src="https://cdnjs.cloudflare.com/ajax/libs/baguettebox.js/1.11.1/baguetteBox.min.js" integrity="sha256-ULQV01VS9LCI2ePpLsmka+W0mawFpEA0rtxnezUj4A4=" crossorigin="anonymous"></script> - {{ social_buttons_code }} - <script src="/assets/js/copybutton.js"></script> - {% if date_fanciness != 0 %} - <!-- fancy dates --> - <script> - luxon.Settings.defaultLocale = "{{ luxon_locales[lang] }}"; - fancydates({{ date_fanciness }}, {{ luxon_date_format }}); - </script> - <!-- end fancy dates --> - {% endif %} - {% block extra_js %}{% endblock %} - <script> - baguetteBox.run('div#content', { - ignoreClass: 'islink', - captions: function(element) { - return element.getElementsByTagName('img')[0].alt; - }}); - </script> -{{ body_end }} -{{ template_hooks['body_end']() }} -</body> -</html> diff --git a/themes/cantera/templates/cxx-example-index.tmpl b/themes/cantera/templates/cxx-example-index.tmpl deleted file mode 100644 index 3eb65b7b6..000000000 --- a/themes/cantera/templates/cxx-example-index.tmpl +++ /dev/null @@ -1,36 +0,0 @@ -{# -*- coding: utf-8 -*- #} -{% extends 'base.tmpl' %} -{% block content %} -<h1 class="display-4">Index of C++ Examples</h1> - -<p>This is an index of the C++ examples included with Cantera.</p> - -{% for head, ex_dict in headers.items() %} - <div class="section" id="cxx-example"> - <h2 class="cxx-example-header example-header"> - {{ ex_dict['name'] }} - <a class="headerlink" href="#cxx-example" title="Permalink to this headline">¶</a> - </h2> - {% for row in ex_dict.names %} - <div class="card-deck cxx-example-row example-row"> - {% for name in row %} - <!-- <div class="col-sm-4"> --> - <div class="card"> - <a href="{{ name }}.html"><h5 class="card-header">{{ ex_dict.titles[name] }}</h5></a> - <div class="card-body"> - <p class="card-text">{{ ex_dict.summaries[name] }}</p> - </div> - </div> - <!-- </div> --> - {% endfor %} - </div> - {% endfor %} - </div> -{% endfor %} -{% endblock %} - -{% block sourcelink %} -{% if source_link and show_sourcelink %} - {{ ui.show_sourcelink(source_link) }} -{% endif %} -{% endblock %} diff --git a/themes/cantera/templates/error.tmpl b/themes/cantera/templates/error.tmpl deleted file mode 100644 index a1c8658ee..000000000 --- a/themes/cantera/templates/error.tmpl +++ /dev/null @@ -1,17 +0,0 @@ -{% extends "base.tmpl" %} - -{% block extra_head %} - {{ super() }} - <base href="{{ blog_url }}"> -{% endblock %} - -{% block content %} -<h2>{{ post.meta('errdesc') }}</h2> -<p class="lead">{{ post.meta('description') }}</p> -{{ post.text() }} -<p> - If you clicked a link on <a href="https://cantera.org">cantera.org</a> and ended up here, please - <a href="https://github.com/Cantera/cantera-website/issues/new">file an issue</a> on the GitHub - repository for this website. -</p> -{% endblock %} diff --git a/themes/cantera/templates/examples.tmpl b/themes/cantera/templates/examples.tmpl deleted file mode 100644 index 4a2f9e176..000000000 --- a/themes/cantera/templates/examples.tmpl +++ /dev/null @@ -1,36 +0,0 @@ -{# -*- coding: utf-8 -*- #} -{% extends 'base.tmpl' %} -{% import 'math_helper.tmpl' as math with context %} -{% block extra_head %} -{% if title.endswith('.ipynb') %} - {{ math.math_styles() }} -{% endif %} -{% endblock %} -{% block content %} -{% if code %} -<h1>{{ title }} - {% if source_link %} - <small><a href="{{ source_link }}">({{ messages("Source") }})</a></small> - {% endif %} - </h1> - {% if data_files %} - Data files used in this example: - {% for i, file in enumerate(data_files) -%} - <a href="https://raw.githubusercontent.com/Cantera/cantera-jupyter/main/data/{{ file }}">{{ file }}</a> - {%- if i + 1 != data_files | length -%} - , - {% endif %} - {% endfor %} - {% endif %} - {{ code }} -{% endif %} -{% if title.endswith('.ipynb') %} - {{ math.jupyter_math_scripts() }} -{% endif %} -{% endblock %} - -{% block sourcelink %} -{% if source_link and show_sourcelink %} - {{ ui.show_sourcelink(source_link) }} -{% endif %} -{% endblock %} diff --git a/themes/cantera/templates/fortran-example-index.tmpl b/themes/cantera/templates/fortran-example-index.tmpl deleted file mode 100644 index f07620b35..000000000 --- a/themes/cantera/templates/fortran-example-index.tmpl +++ /dev/null @@ -1,37 +0,0 @@ -{# -*- coding: utf-8 -*- #} -{% extends 'base.tmpl' %} -{% block content %} -<h1 class="display-4">Index of Fortran Examples</h1> - -<p>This is an index of the Fortran examples included with Cantera.</p> - -{% for head, file_dict in headers.items() %} - <div class="section" id="fortran-example"> - <h2 class="fortran-example-header example-header"> - {{ file_dict['name'] }} - <a class="headerlink" href="#fortran-example" title="Permalink to this headline">¶</a> - </h2> - {% for row in file_dict['files'] %} - <div class="card-deck fortran-example-row example-row"> - {% for file in row %} - {% set fname = file.name %} - <!-- <div class="col-sm-4"> --> - <div class="card"> - <a href="{{ fname }}.html"><h5 class="card-header">{{ file_dict.titles[fname] }}</h5></a> - <div class="card-body"> - <p class="card-text">{{ file_dict['summaries'][fname] }}</p> - </div> - </div> - <!-- </div> --> - {% endfor %} - </div> - {% endfor %} - </div> -{% endfor %} -{% endblock %} - -{% block sourcelink %} -{% if source_link and show_sourcelink %} - {{ ui.show_sourcelink(source_link) }} -{% endif %} -{% endblock %} diff --git a/themes/cantera/templates/home.tmpl b/themes/cantera/templates/home.tmpl deleted file mode 100644 index adb68e33b..000000000 --- a/themes/cantera/templates/home.tmpl +++ /dev/null @@ -1,19 +0,0 @@ -{% import 'math_helper.tmpl' as math with context %} -{% import 'ui_helper.tmpl' as ui with context %} -{% extends 'base.tmpl' %} - -{% block extra_head %} -{{ super() }} -{{ math.math_styles_ifpost(post) }} -{% endblock %} - -{% block content %} - {{ post.text() }} - {{ math.math_scripts_ifpost(post) }} -{% endblock %} - -{% block sourcelink %} -{% if show_sourcelink %} - {{ ui.show_sourcelink(post.source_link()) }} -{% endif %} -{% endblock %} diff --git a/themes/cantera/templates/jupyter-example-index.tmpl b/themes/cantera/templates/jupyter-example-index.tmpl deleted file mode 100644 index be76299d4..000000000 --- a/themes/cantera/templates/jupyter-example-index.tmpl +++ /dev/null @@ -1,59 +0,0 @@ -{# -*- coding: utf-8 -*- #} -{% extends 'base.tmpl' %} -{% block content %} -<h1 class="display-4">Index of Jupyter Notebook Examples</h1> - -<p>Cantera examples in the form of <a href="https://jupyter.org" title="Jupyter">Jupyter</a> -notebooks. To see the rendered notebooks, browse the files below.</p> - -<p><strong>Existing Cantera users</strong>: If you have Cantera and the Jupyter Notebook -server installed on your local machine, simply download any Jupyter notebook by clicking -the "Source" link at the top of each example page and you should be able to run it. For -some examples, you will also need to download the additional data files listed below the -"Source" link. These data files should either be placed in a subdirectory named "data" -one level up from the directory containing the notebook file, or the notebook can be -modified to point to the location of these data files on your computer. Alternatively, -you can download all of these examples and their accompanying data files by cloning the -<a href="https://github.com/Cantera/cantera-jupyter">cantera-jupyter</a> repository from -GitHub. -</p> - -<p><strong>New Cantera Users</strong>: If you don't have an existing Cantera installation and you -just want to experiment, you can give Cantera a test drive in the cloud. Click on the Binder link -below to launch an interactive environment where you can run these examples. For this, there is no -installation required, but you cannot save and resume your work.</p> - -<a href="https://mybinder.org/v2/gh/Cantera/cantera-jupyter/main" rel="nofollow"> - <img src="https://camo.githubusercontent.com/70c5b4d050d4019f4f20b170d75679a9316ac5e5/687474703a2f2f6d7962696e6465722e6f72672f62616467652e737667" alt="Binder" data-canonical-src="https://mybinder.org/badge.svg" style="max-width:100%;"> -</a> - -{% for head, file_dict in headers.items() %} - <div class="section" id="python-example-{{ head }}"> - <h2 class="python-example-header example-header"> - {{ file_dict['name'] }} - <a class="headerlink" href="#python-example-{{ head }}" title="Permalink to this headline">¶</a> - </h2> - {% for row in file_dict['files'] %} - <div class="card-deck python-example-row example-row"> - {% for file in row %} - {% set fname = file.name %} - <!-- <div class="col-sm-4"> --> - <div class="card"> - <a href="{{ head }}/{{ fname }}.html"><h5 class="card-header">{{ file_dict['titles'][fname] }}</h5></a> - <div class="card-body"> - <p class="card-text">{{ file_dict['summaries'][fname] }}</p> - </div> - </div> - <!-- </div> --> - {% endfor %} - </div> - {% endfor %} - </div> -{% endfor %} -{% endblock %} - -{% block sourcelink %} -{% if source_link and show_sourcelink %} - {{ ui.show_sourcelink(source_link) }} -{% endif %} -{% endblock %} diff --git a/themes/cantera/templates/math_helper.tmpl b/themes/cantera/templates/math_helper.tmpl deleted file mode 100644 index 72940b1bd..000000000 --- a/themes/cantera/templates/math_helper.tmpl +++ /dev/null @@ -1,69 +0,0 @@ -{# Note: This file has been edited from the base theme to only include the KaTeX options #} -{# KaTeX urls from: https://katex.org/docs/autorender.html #} - -{% macro math_scripts_files() %} - <script defer src="https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/katex.min.js" integrity="sha384-y23I5Q6l+B6vatafAwxRu/0oK/79VlbSz7Q9aiSZUvyWYIYsd+qj+o24G5ZU2zJz" crossorigin="anonymous"></script> - <script defer src="https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/contrib/auto-render.min.js" integrity="sha384-kWPLUVMOks5AQFrykwIup5lo0m3iMkkHrD0uJ4H5cjeGihAutqP0yW0J6dpFiVkI" crossorigin="anonymous"></script> -{% endmacro %} - -{% macro math_scripts() %} - {{ math_scripts_files() }} - <script> - document.addEventListener("DOMContentLoaded", function() { - renderMathInElement(document.body, { - delimiters: [ - {left: "$$", right: "$$", display: true}, - {left: "\\[", right: "\\]", display: true}, - {left: "\\begin{equation*}", right: "\\end{equation*}", display: true}, - {left: "\\(", right: "\\)", display: false} - ] - }); - }); - </script> -{% endmacro %} - -{% macro jupyter_math_scripts() %} - {{ math_scripts_files() }} - <script> - document.addEventListener("DOMContentLoaded", function() { - renderMathInElement(document.body, { - delimiters: [ - {left: "$$", right: "$$", display: true}, - {left: "\\[", right: "\\]", display: true}, - {left: "\\begin{equation*}", right: "\\end{equation*}", display: true}, - {left: "\\begin{equation}", right: "\\end{equation}", display: true}, - {left: "$", right: "$", display: false}, - {left: "\\(", right: "\\)", display: false} - ] - }); - }); - </script> -{% endmacro %} - -{% macro math_styles() %} - <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/katex.min.css" integrity="sha384-zB1R0rpPzHqg7Kpt0Aljp8JPLqbXI3bhnPWROx27a9N0Ll6ZP/+DiW/UqRcLbRjq" crossorigin="anonymous"> -{% endmacro %} - -{% macro math_scripts_ifpost(post) %} - {% if post.has_math %} - {{ math_scripts() }} - {% endif %} -{% endmacro %} - -{% macro math_scripts_ifposts(posts) %} - {% if posts|selectattr("has_math")|list %} - {{ math_scripts() }} - {% endif %} -{% endmacro %} - -{% macro math_styles_ifpost(post) %} - {% if post.has_math %} - {{ math_styles() }} - {% endif %} -{% endmacro %} - -{% macro math_styles_ifposts(posts) %} - {% if posts|selectattr("has_math")|list %} - {{ math_styles() }} - {% endif %} -{% endmacro %} diff --git a/themes/cantera/templates/matlab-example-index.tmpl b/themes/cantera/templates/matlab-example-index.tmpl deleted file mode 100644 index 992e3eb71..000000000 --- a/themes/cantera/templates/matlab-example-index.tmpl +++ /dev/null @@ -1,37 +0,0 @@ -{# -*- coding: utf-8 -*- #} -{% extends 'base.tmpl' %} -{% block content %} -<h1 class="display-4">Index of Matlab Examples</h1> - -<p>This is an index of the examples included with the Cantera Matlab toolbox.</p> - -{% for head, file_dict in headers.items() %} - <div class="section" id="matlab-example"> - <h2 class="matlab-example-header example-header"> - {{ file_dict['name'] }} - <a class="headerlink" href="#matlab-example" title="Permalink to this headline">¶</a> - </h2> - {% for row in file_dict['files'] %} - <div class="card-deck matlab-example-row example-row"> - {% for file in row %} - {% set fname = file.name %} - <!-- <div class="col-sm-4"> --> - <div class="card"> - <a href="{{ fname }}.html"><h5 class="card-header">{{ fname }}</h5></a> - <div class="card-body"> - <p class="card-text">{{ file_dict['summaries'][fname] }}</p> - </div> - </div> - <!-- </div> --> - {% endfor %} - </div> - {% endfor %} - </div> -{% endfor %} -{% endblock %} - -{% block sourcelink %} -{% if source_link and show_sourcelink %} - {{ ui.show_sourcelink(source_link) }} -{% endif %} -{% endblock %} diff --git a/themes/cantera/templates/multifile-example.tmpl b/themes/cantera/templates/multifile-example.tmpl deleted file mode 100644 index 65a0397cb..000000000 --- a/themes/cantera/templates/multifile-example.tmpl +++ /dev/null @@ -1,19 +0,0 @@ -{# -*- coding: utf-8 -*- #} -{% extends 'base.tmpl' %} -{% import 'math_helper.tmpl' as math with context %} -{% block content %} - {% for item in items %} - {% if item.code %} - <h1>{{ item.title }} - {% if item.source_link %} - <small><a href="{{ item.source_link }}">({{ messages("Source") }})</a></small> - {% endif %} - </h1> - {{ item.code }} - {% endif %} - - {% if item.source_link and show_sourcelink %} - {{ ui.show_sourcelink(item.source_link) }} - {% endif %} - {% endfor %} -{% endblock %} diff --git a/themes/cantera/templates/page.tmpl b/themes/cantera/templates/page.tmpl deleted file mode 100644 index e513b4f1a..000000000 --- a/themes/cantera/templates/page.tmpl +++ /dev/null @@ -1,12 +0,0 @@ -{# -*- coding: utf-8 -*- #} -{% import 'math_helper.tmpl' as math with context %} -{% extends 'post.tmpl' %} - -{% block content %} -<article class="post-{{ post.meta('type') }} storypage" itemscope="itemscope" itemtype="http://schema.org/Article"> - <div class="e-content entry-content" itemprop="articleBody text"> - {{ post.text() }} - </div> - {{ math.math_scripts_ifpost(post) }} -</article> -{% endblock %} diff --git a/themes/cantera/templates/python-example-index.tmpl b/themes/cantera/templates/python-example-index.tmpl deleted file mode 100644 index 2babc9802..000000000 --- a/themes/cantera/templates/python-example-index.tmpl +++ /dev/null @@ -1,45 +0,0 @@ -{# -*- coding: utf-8 -*- #} -{% extends 'base.tmpl' %} -{% block content %} -<h1 class="display-4">Index of Python Examples</h1> - -<p>This is an index of Python examples included with Cantera.</p> - -<p>Cantera's Python examples can be downloaded by clicking the "Source" link at the top -of each example page.</p> - -<h3>Table of Contents</h3> -<ul> -{% for head, file_dict in headers.items() %} -<li><a href="#python-example-{{ head }}" title="Python {{ file_dict['name'] }} Examples">{{ file_dict['name'] }}</a></li> -{% endfor %} -</ul> - -{% for head, file_dict in headers.items() %} - <div class="section" id="python-example-{{ head }}"> - <h3 class="python-example-header example-header"> - {{ file_dict['name'] }} - <a class="headerlink" href="#python-example-{{ head }}" title="Permalink to this headline">¶</a> - </h3> - {% for row in file_dict['files'] %} - <div class="card-deck python-example-row example-row"> - {% for file in row %} - {% set fname = file.name %} - <div class="card"> - <a href="{{ head }}/{{ fname }}.html"><h5 class="card-header">{{ fname }}</h5></a> - <div class="card-body"> - <p class="card-text">{{ file_dict['summaries'][fname] }}</p> - </div> - </div> - {% endfor %} - </div> - {% endfor %} - </div> -{% endfor %} -{% endblock %} - -{% block sourcelink %} -{% if source_link and show_sourcelink %} - {{ ui.show_sourcelink(source_link) }} -{% endif %} -{% endblock %}