Add Plasma and Trapping SINDy notebooks to example index; attempt to …

…fix formatting for math in trapping SINDy notebook

examples/8_trapping_sindy_paper_examples.ipynb

@@ -615,31 +615,20 @@
     "# Mean field model\n",
     "Often the trajectories of nonlinear dynamical systems whose linear parts have some stable directions will approach slow manifolds of reduced dimension with respect to the full state space.\n",
     "As an example of this behavior, consider the following linear-quadratic system originally proposed by Noack et al. (2003) as a simplified model of the von Karman vortex shedding problem:\n",
-    "$$ \n",
-    "    \\frac{d}{dt}\\begin{bmatrix}\n",
-    "    x \\\\ \n",
-    "    y \\\\\n",
-    "    z \\\\\n",
-    "    \\end{bmatrix} = \\begin{bmatrix}\n",
-    "    \\mu & -1 & 0 \\\\\n",
-    "    1 & \\mu & 0 \\\\\n",
-    "    0 & 0 & -1 \\\\\n",
-    "    \\end{bmatrix}\\begin{bmatrix}\n",
-    "    x \\\\ \n",
-    "    y \\\\\n",
-    "    z \n",
-    "    \\end{bmatrix}\n",
-    "    +\n",
-    "    \\begin{bmatrix}\n",
-    "    - xz \\\\ - yz \\\\ x^2 + y^2\n",
-    "    \\end{bmatrix}.\n",
     "$$\n",
+    "    \\frac{d}{dt}\\begin{bmatrix}x \\\\ y \\\\z \\end{bmatrix}\n",
+    "    = \\begin{bmatrix} \\mu & -1 & 0 \\\\1 & \\mu & 0 \\\\ 0 & 0 & -1 \\\\ \\end{bmatrix}\n",
+    "    \\begin{bmatrix} x \\\\ y \\\\z \\end{bmatrix}\n",
+    "    + \\begin{bmatrix}- xz \\\\ - yz \\\\ x^2 + y^2\\end{bmatrix}.\n",
+    "$$\n",
+    "\n",
     "\n",
     "Systems of this form commonly arise in PDEs with a pair of unstable eigenmodes represented by $x$ and $y$.\n",
     "The third variable $z$ models the effects of mean-field deformations due to nonlinear self-interactions of the instability modes.\n",
     "The linear component is the generic linear part of a system undergoing a supercritical Hopf bifurcation at $\\mu = 0$; for $\\mu \\ll 1$ trajectories quickly approach the parabolic manifold defined by $z = x^2 + y^2$.\n",
     "All solutions asymptotically approach a stable limit cycle on which $z = x^2 + y^2 = \\mu$.\n",
     "It is enough to notice that $\\mathbf{m} = [0, 0, \\mu+\\epsilon]$, $\\epsilon > 0$ produces a negative definite matrix\n",
+    "\n",
     "$$\n",
     "\\begin{align}\n",
     "    \\mathbf{A}^S = \\mathbf{L}^S - \\mathbf{m}\\mathbf{Q} = \\begin{bmatrix}\n",
@@ -649,6 +638,7 @@
     "    \\end{bmatrix},\n",
     "\\end{align}\n",
     "$$\n",
+    "\n",
     "so this system exhibits a trapping region. We can show this analytically, and illustrate below our algorithm can discover it."
    ]
   },
@@ -854,6 +844,7 @@
    "source": [
     "# Atmospheric oscillator model\n",
     "Here we briefly look at a more complicated Lorenz-like system of coupled oscillators that is motivated from atmospheric dynamics. The model is\n",
+    "\n",
     "$$\n",
     "\\begin{align}\n",
     "\\label{eq:oscillator}\n",
@@ -878,6 +869,7 @@
     "    \\end{bmatrix}.\n",
     "\\end{align}\n",
     "$$\n",
+    "\n",
     "For comparison, we assume the parameter choices in Tuwankotta et al. (2006), $\\mu_1 = 0.05$, $\\mu_2 = -0.01$, $\\omega = 3$, $\\sigma = 1.1$, $\\kappa = -2$, and $\\beta = -6$, for which a limit cycle is known to exist. Again, the algorithm shows straightforward success finding a model with a trapping region, for a range of hyperparameter values."
    ]
   },
@@ -1120,6 +1112,7 @@
     "# Lorenz model\n",
     "The Lorenz system originates from a simple fluid model of atmospheric dynamics from Lorenz et al. (1963).\n",
     "This system is likely the most famous example of chaotic, nonlinear behavior despite the somewhat innocuous system of equations,\n",
+    "\n",
     "$$\n",
     "\\begin{align}\n",
     "    \\frac{d}{dt}\\begin{bmatrix}\n",
@@ -1149,7 +1142,9 @@
     "    \\end{bmatrix}.\n",
     "\\end{align}\n",
     "$$\n",
+    "\n",
     "For Lorenz's choice of parameters, $\\sigma = 10$, $\\rho = 28$, $\\beta  = 8/3$, this system is known to exhibit a stable attractor. For $\\mathbf{m} = [0,m_2,\\rho+\\sigma]$ ($m_1$ does not contribute to $\\mathbf{A}^S$ so we set it to zero),\n",
+    "\n",
     "$$\n",
     "\\begin{align}\n",
     "    \\mathbf{A}^S &= \\begin{bmatrix}\n",
@@ -1160,6 +1155,7 @@
     "    \\lambda_1 = -1, \\qquad \\lambda_{\\pm} = -\\frac{1}{2}\\left[\\beta+\\sigma \\mp \\sqrt{m_2^2 + (\\beta-\\sigma)^2}\\right],\n",
     "\\end{align}\n",
     "$$\n",
+    "\n",
     "so that if $\\lambda_{\\pm} < 0$, then $-2\\sqrt{\\sigma\\beta} < m_2 < 2\\sqrt{\\sigma\\beta}$. \n",
     "Our algorithm can successfully identify the optimal $\\mathbf{m}$, and can be used to identify the inequality bounds on $m_2$ for stability. "
    ]
@@ -1829,6 +1825,7 @@
     "# MHD model\n",
     "Magnetohydrodynamics exhibit quadratic nonlinearities that are often energy-preserving with typical boundary conditions. \n",
     "We consider a simple model of the nonlinearity in 2D incompressible MHD, which can be obtained from Fourier-Galerkin projection onto a single triad of wave vectors. For the wave vectors $(1,1)$, $(2,-1)$, and $(3,0)$ and no background magnetic field, the Carbone and Veltri (1992) system is \n",
+    "\n",
     "$$\n",
     "\\begin{align}\n",
     "\\label{eq:simpleMHD_model}\n",
@@ -1863,6 +1860,7 @@
     "    \\end{bmatrix},\n",
     "\\end{align}\n",
     "$$\n",
+    "\n",
     "where $\\nu \\geq 0$ is the viscosity and $\\mu \\geq 0$ is the resistivity. Without external forcing, this system is trivially stable (it dissipates to zero), so we consider the inviscid limit $\\nu = \\mu = 0$. The system is then Hamiltonian and our algorithm correctly converges to $\\mathbf{m} = 0$, $\\mathbf{A}^S = 0$. The reason our algorithm converges to the correct behavior is because it is still minimizing $\\dot{K}$; in this case trapping SINDy minimizes to $\\dot{K} \\approx 0$ and can make no further improvement."
    ]
   },
@@ -2154,21 +2152,25 @@
    "source": [
     "# Forced Burger's Equation\n",
     "The viscous Burgers' equation has long served as a simplified one-dimensional turbulence analogue (Burgers/Hopf 1948). The forced, viscous Burgers' equation on a periodic domain $x \\in [0,2\\pi)$ is:\n",
+    "\n",
     "$$\n",
     "\\begin{align}\n",
     "\\label{eq:burgers}\n",
     "    \\dot{u} &= -(U + u)\\partial_x u + \\nu \\partial_{xx}^2u + g(x,t),\n",
     "\\end{align}\n",
     "$$\n",
+    "\n",
     "where $\\nu$ is viscosity and the constant $U$ models mean-flow advection. \n",
     "We project this system onto a Fourier basis and assume constant forcing acting on the largest scale, i.e. $g(x, t) = \\sigma \\left( a_1(t) e^{ix} + a_{-1}(t) e^{-ix} \\right)$ as in Noack and Schlegel et al. (2008).\n",
     "After Fourier projection, the evolution of the coefficients $a_k(t)$ is given by the Galerkin dynamics\n",
+    "\n",
     "$$\n",
     "\\begin{equation}\n",
     "\\label{eq:burgers_galerkin}\n",
     "    \\dot{a}_k = \\left( \\delta_{|k|1} \\sigma - \\nu k^2  - ikU \\right) a_k - \\sum_{\\ell=-r}^{r} i \\ell a_{\\ell} a_{k - \\ell}.\n",
     "\\end{equation}\n",
     "$$\n",
+    "\n",
     "In the subcritical case $\\sigma < \\nu$ the origin of this system is stable to all perturbations and all solutions decay on long times.\n",
     "However, in the supercritical case $\\sigma > \\nu$ the excess energy input from the forcing cascades to the smaller dissipative scales. \n",
     "The absolute equilibrium limit $\\sigma = \\nu = 0$ has a Hamiltonian structure; at long times the coefficients approach thermodynamic equilibrium and equipartition of energy. For the supercritical condition $\\sigma > \\nu$, the trapping SINDy algorithm does not converge to a negative definite $\\mathbf{A}^S$ because this system does not exhibit effective nonlinearity. "

examples/README.rst

@@ -34,9 +34,19 @@ Shows how PySINDy interfaces with various Scikit-learn objects.
 ---------------------------------------------------------------------------------------------------------
 Explore the differentiation methods available in PySINDy on pure differentiation problems and as components in the SINDy algorithm.
 
-`Scikit-time compatibility <https://pysindy.readthedocs.io/en/latest/examples/6_scikit_time_compatibility.html>`_
+`Deeptime compatibility <https://pysindy.readthedocs.io/en/latest/examples/6_deeptime_compatibility.html>`_
 ------------------------------------------------------------------------------------------------------------------------
-See a demonstration of PySINDy objects designed to conform to the `Scikit-time <https://scikit-time.github.io/>`_ API.
+See a demonstration of PySINDy objects designed to conform to the `Deeptime <https://deeptime-ml.github.io/latest/index.html>`_ API.
+
+`Plasma physics <https://pysindy.readthedocs.io/en/latest/examples/7_plasma_example.htm>`_
+----------------------------------------------------------------------------------------------
+See the ``ConstrainedSR3`` optimizer used to build a constrained model for the temporal POD modes of a plasma simulation.
+
+
+`Plasma physics <https://pysindy.readthedocs.io/en/latest/examples/8_trapping_sindy_paper_examples.htm>`_
+----------------------------------------------------------------------------------------------
+This notebook applies the ``TrappingSR3`` optimizer, proposed in `this paper <https://arxiv.org/abs/2105.01843>`_, to various canonical fluid systems.
+
 
 Full table of contents
 ----------------------