small docs updates

Author: shanemcq18

.github/workflows/test_docs.yml

@@ -1,5 +1,5 @@
 # test_docs.yml
-# Build the documentation, the same as would be done locally with `make test`.
+# Build the documentation, the same as would be done locally with `make docs`.
 name: CI-docs
 
 on:

Makefile

@@ -33,7 +33,7 @@ test: lint install
 
 
 docs:
-	jupyter-book build docs
+	jupyter-book build docs -n -W --keep-going
 
 
 deploy: test docs

docs/_config.yml

@@ -50,7 +50,9 @@ sphinx:
     # MathJax 3 (faster than the default).
     mathjax_path: https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
     # language: en
-    numfig_secnum_depth: 2  # Eq (1.1.1) instead of (1)
+    numfig_secnum_depth: 1            # Eq (1.1) instead of (1)
+    bibtex_reference_style: label
+    # bibtex_default_style: plain     # Citations as numbers
   extra_extensions:
     - sphinx_design
     - sphinxcontrib.mermaid

docs/_toc.yml

@@ -9,8 +9,8 @@ parts:
     # numbered: 1
     chapters:
     - file: content/opinf/intro.md
-    # - file: content/opinf/literature.md
     - file: content/opinf/installation.md
+    # - file: content/opinf/literature.md
 
   # How to use the package.
   - caption: Package Usage

docs/content/contributing/code_anatomy.md

@@ -48,7 +48,7 @@ The `pre` module contains all transformer and basis class definitions.
 Transformers and bases can be _monolithic_ (treating the state as one variable) or _multivariable_ (treating different chunks of the state as separate variables).
 Multivariable transformers and bases inherit from `pre._multivar._MultivarMixin` and should have, as attributes, a list of monolithic counterparts.
 
-Read [Data Normalization](sec-normalization) and [Basis Computation](sec-basis-computation) before starting work here.
+Read [Data Scaling](sec-pre-scaling) and [Basis Computation](sec-basis-computation) before starting work here.
 
 (subsec-contrib-transformerclass)=
 ### Transformer Classes

docs/content/opinf/installation.md

@@ -1,5 +1,5 @@
 (sec-installation)=
-# Installation
+# Package Installation
 
 This page describes how to install `rom_operator_inference` locally.
 

docs/content/opinf/intro.md

@@ -153,7 +153,7 @@ Common preprocessing steps include
 2. Centering or shifting data to account for boundary conditions.
 3. Scaling / nondimensionalizing the variables represented in the state.
 
-See [Data Normalization](sec-normalization) for details and examples.
+See [Data Scaling](sec-pre-scaling) for details and examples.
 :::
 
 Operator Inference uses a regression problem to compute the reduced-order operators, which requires state data ($\mathbf{Q}$), input data ($\mathbf{U}$), _and_ data for the corresponding time derivatives:

docs/content/tutorials/basics.ipynb

@@ -641,17 +641,11 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    ":::{tip}\n",
+    "::::{tip}\n",
     "The class `opinf.pre.PODBasis` conveniently combines basis construction and dimension selection. The `fit()` method receives the state matrix $\\mathbf{Q}$ and either the desired reduced dimension $r$ or a threshold value for selecting $r$ based on the cumulative or residual energy.\n",
     "\n",
-    "python```\n",
-    ">>> basis = opinf.pre.PODBasis().fit(Q, r=2)\n",
-    ">>> basis.shape == Vr.shape and np.all(basis.entries == Vr)\n",
-    "True\n",
-    "```\n",
-    "\n",
     "The next tutorial uses the `PODBasis` class instead of the `pod_basis()` function.\n",
-    ":::"
+    "::::"
    ]
   },
   {

docs/content/tutorials/gallery.md

@@ -880,7 +880,7 @@
    "source": [
     ":::{admonition} On Convergence\n",
     ":class: warning\n",
-    "The figure above conveys a sense of convergence: as the reduced dimension $r$ increases, the ROM error decreases. In more complex problems, **the error does not always decrease monotinically as $r$ increases**. In fact, at some point as $r$ increases performance often deteriorates significantly due to poor conditioning in the operator inference regression. In practice, choose a reduced dimension $r$ that balances solution accuracy with computational speed, not too small but also not too large.\n",
+    "The figure above conveys a sense of convergence: as the reduced dimension $r$ increases, the ROM error decreases. In more complex problems, **the error does not always decrease monotonically as $r$ increases**. In fact, at some point as $r$ increases performance often deteriorates significantly due to poor conditioning in the operator inference regression. In practice, choose a reduced dimension $r$ that balances solution accuracy with computational speed, not too small but also not too large.\n",
     ":::"
    ]
   },
@@ -1537,7 +1537,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "plot_state_error(15, run_trial_parametric, \"Average relative\\nFrobenius-norm error\")"
+    "plot_state_error(14, run_trial_parametric, \"Average relative\\nFrobenius-norm error\")"
    ]
   }
  ],

docs/content/tutorials/heat_equation.ipynb

@@ -24,7 +24,7 @@ Operator Inference learns a reduced-order model that determines the evolution of
 This chapter discusses modeling choices for $\boldsymbol{\Gamma}$, the mapping that bridges the latent coordinates and the original state space.
 We approach this in two stages.
 
-**Data normalization.**
+**Data scaling.**
 Raw dynamical systems data often need to be lightly preprocessed before use in Operator Inference.
 Common preprocessing steps include
 1. Variable transformations / lifting to induce a polynomial structure.

docs/content/usage/preprocessing/index.md

@@ -1,5 +1,5 @@
-(sec-normalization)=
-# Data Normalization
+(sec-pre-scaling)=
+# Data Scaling
 
 :::{attention}
 This page is under construction.

docs/content/usage/preprocessing/transformers.md

@@ -2,7 +2,7 @@
 
 @article{benner2015pmorsurvey,
     title = {A survey of projection-based model reduction methods for parametric dynamical systems},
-    author = {Benner, Peter and G{\"u}{\u{g}}ercin, Serkan and Willcox, Karen},
+    author = {Benner, Peter and Gugercin, Serkan and Willcox, Karen},
     journal = {SIAM Review},
     volume = {57},
     number = {4},
@@ -22,6 +22,17 @@ @article{benner2020opinfdeim
     doi = {10.1016/j.cma.2020.113433},
 }
 
+@article{ghattas2021learning,
+    title = {Learning physics-based models from data: perspectives from inverse problems and model reduction},
+    author = {Ghattas, Omar and Willcox, Karen},
+    journal = {Acta Numerica},
+    volume = {30},
+    pages = {445--554},
+    year = {2021},
+    publisher = {Cambridge University Press},
+    doi = {10.1017/S0962492921000064},
+}
+
 @article{halko2011rnla,
     title = {Finding structure with randomness: {P}robabilistic algorithms for constructing approximate matrix decompositions},
     author = {Halko, Nathan and Martinsson, Per-Gunnar and Tropp, Joel A},
@@ -52,12 +63,12 @@ @article{khodabakhshi2022diffalg
     pages = {114296},
     year = {2022},
     issn = {0045-7825},
-    doi = {doi.org/10.1016/j.cma.2021.114296},
+    doi = {10.1016/j.cma.2021.114296},
 }
 
 @article{mcquarrie2021combustion,
-    author = {Shane A. McQuarrie and Cheng Huang and Karen E. Willcox},
     title = {Data-driven reduced-order models via regularised Operator Inference for a single-injector combustion process},
+    author = {Shane A. McQuarrie and Cheng Huang and Karen E. Willcox},
     journal = {Journal of the Royal Society of New Zealand},
     volume = {51},
     number = {2},
@@ -69,7 +80,7 @@ @article{mcquarrie2021combustion
 
 @article{peherstorfer2016opinf,
     title = {Data-driven operator inference for nonintrusive projection-based model reduction},
-    author = {Peherstorfer, B. and Willcox, K.},
+    author = {Peherstorfer, Benjamin and Willcox, Karen},
     journal = {Computer Methods in Applied Mechanics and Engineering},
     volume = {306},
     pages = {196--215},