Cantera · speth · Jun 25, 2024 · Jun 12, 2024 · Jun 12, 2024 · Jun 12, 2024
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -457,7 +457,6 @@ jobs:
       - name: Run the examples
         # See https://unix.stackexchange.com/a/392973 for an explanation of the -exec part.
         # Skip 1D_packed_bed.py due to difficulty installing scikits.odes.
-        # Skip continuous_reactor.py due to thermo warnings
         # Increase figure limit to handle flame_speed_convergence_analysis.py.
         run: |
           ln -s libcantera_shared.so build/lib/libcantera_shared.so.3
@@ -471,7 +470,8 @@ jobs:
           # The pyparsing ignore setting is due to a new warning introduced in Matplotlib==3.6.0
           # @todo: Remove the trapz-related ignore when dropping support for NumPy 1.x
           #     and replacing np.trapz with np.trapezoid
-          PYTHONWARNINGS: "error,ignore:warn_name_set_on_empty_Forward::pyparsing,ignore:datetime.datetime.utcfromtimestamp:DeprecationWarning:,ignore:`trapz`:DeprecationWarning"
+          # Ignore NasaPoly2 warnings from n-hexane-NUIG-2015.yaml
+          PYTHONWARNINGS: "error,ignore:warn_name_set_on_empty_Forward::pyparsing,ignore:datetime.datetime.utcfromtimestamp:DeprecationWarning:,ignore:`trapz`:DeprecationWarning,ignore:NasaPoly2:UserWarning:"
           MPLBACKEND: Agg
       - name: Save the results file for inspection
         uses: actions/upload-artifact@v4

diff --git a/doc/SConscript b/doc/SConscript
@@ -54,10 +54,14 @@ if localenv['sphinx_docs']:
                                     "#CONTRIBUTING.md",
                                     Copy("$TARGET", "$SOURCE"))
 
+    copy_switcher = localenv.Command("#build/doc/html/dev/_static/doc-versions.json",
+                                     "sphinx/_static/doc-versions.json",
+                                     Copy("$TARGET", "$SOURCE"))
+
     sphinxdocs = build(localenv.Command('#build/doc/html/index.html',
         'sphinx/conf.py', build_sphinx))
     env.Alias('sphinx', sphinxdocs)
-    env.Depends(sphinxdocs, [copy_sphinx, copy_contrib])
+    env.Depends(sphinxdocs, [copy_sphinx, copy_contrib, copy_switcher])
     env.Depends(sphinxdocs, [copy_python_samples, copy_matlab_ex_samples])
     env.Depends(sphinxdocs, env['python_module'])
 

diff --git a/doc/doxygen/Doxyfile b/doc/doxygen/Doxyfile
@@ -1355,7 +1355,7 @@ HTML_EXTRA_FILES       = ext/doxygen-awesome-css/doxygen-awesome-darkmode-toggle
 # The default value is: AUTO_LIGHT.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_COLORSTYLE        = AUTO_LIGHT
+HTML_COLORSTYLE        = LIGHT
 
 # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen
 # will adjust the colors in the style sheet and background images according to

diff --git a/doc/sphinx/_static/custom.css b/doc/sphinx/_static/custom.css
@@ -47,3 +47,10 @@ div.admonition.tip>.admonition-title:after {
   color:var(--pst-color-info);
   content:var(--pst-icon-admonition-tip)
 }
+
+div.highlight pre {
+    /* Reduced padding around code blocks from default of 1 rem */
+    padding: .5rem;
+    /* Slight reduction in font size so 80 characters fit on most display sizes */
+    font-size: 0.78rem;
+}
diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py
@@ -57,7 +57,7 @@
     'ignore_pattern': r'(__.*__\.py|test_examples\.m)',
     'image_srcset': ["2x"],
     'remove_config_comments': True,
-    'ignore_repr_types': r'matplotlib\.(text|axes|legend)',
+    'ignore_repr_types': r'(matplotlib\.(text|axes|legend)|graphviz\.(sources\.Source|graphs\.Graph|graphs\.Digraph))',
     'image_scrapers': ('matplotlib', ctutils.GraphvizScraper()),
     'examples_dirs': [
        '../samples/python/',
@@ -79,8 +79,6 @@
         '../samples/python/transport',
         '../samples/python/reactors',
         '../samples/python/onedim',
-        '../samples/python/surface_chemistry',
-        '../samples/python/multiphase',
     ]),
     'reference_url': {
         'cantera': None,  # 'None' means the locally-documented module
@@ -98,6 +96,13 @@
     "multiprocessing_viscosity.py",
 }
 
+# Installing scikits.odes is challenging on lots of systems (such as Apple Silicon), so
+# just skip running this example if it's not present.
+try:
+    import scikits.odes
+except ImportError:
+    skip_run.add("1D_packed_bed.py")
+
 def executable_script(src_file, gallery_conf):
     """Validate if script has to be run according to gallery configuration.
 
@@ -325,7 +330,6 @@ def escape_splats(app, what, name, obj, options, lines):
     "primary_sidebar_end": ["numfocus"],
     "switcher": {
         "json_url": "/dev/_static/doc-versions.json",
-        # "json_url": "https://cantera.org/doc-versions.json",
         "version_match": version,
     },
     "check_switcher": False,

diff --git a/doc/sphinx/ctutils.py b/doc/sphinx/ctutils.py
@@ -41,9 +41,9 @@ def __call__(self, block, block_vars, gallery_conf):
         # a path to a file name that adheres to Sphinx-Gallery naming convention.
         image_path_iterator = block_vars['image_path_iterator']
 
-        # Define a list of our already-created figure objects.
+        graph_types = (graphviz.Source, graphviz.graphs.Digraph, graphviz.graphs.Graph)
         for obj in block_vars["example_globals"].values():
-            if isinstance(obj, graphviz.Source) and id(obj) not in self.processed:
+            if isinstance(obj, graph_types) and id(obj) not in self.processed:
                 self.processed.add(id(obj))
                 image_path = Path(next(image_path_iterator)).with_suffix(".svg")
                 obj.format = "svg"

diff --git a/doc/sphinx/develop/doc-formatting.md b/doc/sphinx/develop/doc-formatting.md
@@ -33,6 +33,8 @@ This page provides some notes on useful syntax for writing in these various form
   - `[](/absolute-subdir/docname)` (automatically get the text from `docname`'s title)
   - `[link text](relative-subdir/docname)` (explicitly specified link text)
   - source file extension is optional
+- Linking to examples:
+  - ``` [`example_name.py`](/examples/python/subdir/example_name) ```
 - Linking to a labeled section:
   - `[Build Commands](sec-build-commands)`
 - Labeling a section: Above the heading, write:

diff --git a/doc/sphinx/examples/index.md b/doc/sphinx/examples/index.md
@@ -5,6 +5,13 @@ particular programming language, select the corresponding category below. Or, to
 all examples covering a particular topic, regardless of programming language, select
 from the {ref}`list of example tags <tagoverview>`.
 
+```{seealso}
+If you're just getting started with Cantera, see our [](/userguide/python-tutorial) for
+an introduction to the Cantera Python interface, or the
+[C++ Tutorial](/userguide/cxx-tutorial) for some guidance on using Cantera's C++
+interface.
+```
+
 ## Python Examples
 
 ````{grid} 2 2 2 3
@@ -40,18 +47,6 @@ from the {ref}`list of example tags <tagoverview>`.
 :text-align: center
 ```
 
-```{grid-item-card} Surface chemistry
-:link: python/surface_chemistry/index
-:link-type: doc
-:text-align: center
-```
-
-```{grid-item-card} Multiphase
-:link: python/multiphase/index
-:link-type: doc
-:text-align: center
-```
-
 ````
 
 ## Examples in Other Languages

diff --git a/doc/sphinx/reference/glossary.md b/doc/sphinx/reference/glossary.md
@@ -7,6 +7,10 @@ the names of variables and classes:
 CK
 : Chemkin
 
+{.glossary}
+CSTR
+: [Continuous stirred tank reactor](/examples/python/reactors/continuous_reactor)
+
 {.glossary}
 CT
 : Cantera
@@ -19,6 +23,14 @@ CTI
 CTML
 : Cantera Markup Language *(Removed in Cantera 3.0)*
 
+{.glossary}
+DAE
+: Differential algebraic equation
+
+{.glossary}
+EOS / EoS
+: Equation of state
+
 {.glossary}
 HKFT
 : Helgeson-Kirkham-Flowers-Tanger
@@ -31,14 +43,34 @@ HMW
 IAPWS
 : International Association for the Properties of Water and Steam
 
+{.glossary}
+IDT
+: Ignition delay time
+
 {.glossary}
 MFTP
 : Mixture Fugacity ThermoPhase
 
+{.glossary}
+NTC
+: Negative temperature coefficient
+
+{.glossary}
+ODE
+: Ordinary differential equation
+
 {.glossary}
 PDSS
 : Pressure-dependent standard state
 
+{.glossary}
+PFR
+: [Plug flow reactor](./reactors/pfr)
+
+{.glossary}
+PSR
+: [Perfectly stirred reactor](/examples/python/reactors/continuous_reactor)
+
 {.glossary}
 RT
 : Product of the universal gas constant (R) and the temperature
@@ -78,3 +110,7 @@ VPSSTP
 {.glossary}
 wrt
 : with respect to
+
+{.glossary}
+WSR
+: [Well-stirred reactor](/examples/python/reactors/continuous_reactor)
diff --git a/doc/sphinx/reference/reactors/pfr.md b/doc/sphinx/reference/reactors/pfr.md
@@ -124,4 +124,4 @@ $du/dz$, $dp/dz$, $dT/dz$, and $dY_k/dz$ at $z=0$.
 
 - [Partial oxidation of methane over a platinum catalyst](/examples/python/reactors/surf_pfr)
 - [silicon nitride (Si3N4) deposition from ammonia (NH3) and silicon tetrafluoride
-  (SiF4)](/examples/python/surface_chemistry/1D_pfr_surfchem)
+  (SiF4)](/examples/python/reactors/1D_pfr_surfchem)
diff --git a/doc/sphinx/reference/releasenotes/v3.0.md b/doc/sphinx/reference/releasenotes/v3.0.md
@@ -11,7 +11,7 @@ The Cantera development team is pleased to announce the availability of Cantera
 - 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`](/examples/python/onedim/flame_initial_guess))
 - 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 {ct}`CoverageDependentSurfPhase`, [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 (class {py:class}`~cantera.FlowReactor`, [`1D_pfr_surfchem.py`](/examples/python/surface_chemistry/1D_pfr_surfchem), [`surf_pfr.py`](/examples/python/reactors/surf_pfr), [#1490](https://github.com/Cantera/cantera/pull/1490))
+- Add support for surface chemistry to the plug flow reactor model (class {py:class}`~cantera.FlowReactor`, [`1D_pfr_surfchem.py`](/examples/python/reactors/1D_pfr_surfchem), [`surf_pfr.py`](/examples/python/reactors/surf_pfr), [#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`](/yaml/yaml2ck), [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`](/python/units), [`isentropic_units.py`](/examples/python/thermo/isentropic_units), [`rankine_units.py`](/examples/python/thermo/rankine_units), [`sound_speed_units.py`](/examples/python/thermo/sound_speed_units), [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))

diff --git a/doc/sphinx/userguide/ck2yaml-tutorial.md b/doc/sphinx/userguide/ck2yaml-tutorial.md
@@ -58,6 +58,7 @@ thermo file. For example:
 ck2yaml --thermo=therm.dat
 ```
 
+(sec-debugging-chemkin)=
 ## Debugging common errors in CK files
 
 When `ck2yaml` encounters an error, it attempts to print the surrounding information to