<!-- dom:TITLE: How various formats can deal with LaTeX math -->
# How various formats can deal with LaTeX math
<!-- dom:AUTHOR: Hans Petter Langtangen at Simula Research Laboratory & University of Oslo -->
<!-- Author: --> **Hans Petter Langtangen**, Simula Research Laboratory and University of Oslo

Date: **May 25, 2016**

**Summary.** The purpose of this document is to
test LaTeX math in DocOnce with various output formats.
Most LaTeX math constructions are renedered correctly by MathJax
in plain HTML, but some combinations of constructions may fail.
Unfortunately, only a subset of what works in html MathJax also works in
sphinx MathJax. The same is true for markdown MathJax expresions
(e.g., Jupyter notebooks).
Tests and examples are provided to illustrate what may go wrong.

The recommendation for writing math that translates to MathJax in
html, sphinx, and markdown is to stick to the environments
`\[ ... \]`, `equation`, `equation*`, `align`, `align*`, `alignat`,
and `alignat*` only. Test the math with sphinx output; if it works in that
format, it should work elsewhere too.

The current version of the document is translated from DocOnce source
to the format **ipynb**.




**Test 1: Inline math.** We can get an inline equation
`$u(t)=e^{-at}$` rendered as $u(t)=e^{-at}$.

**Test 2: A single equation with label.** An equation with number,

        !bt
        \begin{equation} u(t)=e^{-at} \label{eq1a}\end{equation}
        !et


looks like

<!-- Equation labels as ordinary links -->
<div id="eq1a"></div>

$$
\begin{equation} u(t)=e^{-at} \label{eq1a} \tag{1}\end{equation}
$$

Maybe this multi-line version is what we actually prefer to write:

        !bt
        \begin{equation}
        u(t)=e^{-at}
        \label{eq1b}
        \end{equation}
        !et


The result is the same:

<!-- Equation labels as ordinary links -->
<div id="eq1b"></div>

$$
\begin{equation}
u(t)=e^{-at} \label{eq1b} \tag{2}
\end{equation}
$$

We can refer to this equation through its label `eq1b`: [(2)](#eq1b).


**Test 3: Multiple, aligned equations without label and number.** MathJax has
historically had some problems with rendering many LaTeX math environments,
but the `align*` and `align` environments have always worked.

        !bt
        \begin{align*}
        u(t)&=e^{-at}\\
        v(t) - 1 &= \frac{du}{dt}
        \end{align*}
        !et


Result:

$$
u(t)=e^{-at}
$$

$$
v(t) - 1 = \frac{du}{dt}
$$

**Test 4: Multiple, aligned equations with label.** Here, we
use `align` with user-prescribed labels:

        !bt
        \begin{align}
        u(t)&=e^{-at}
        \label{eq2b}\\
        v(t) - 1 &= \frac{du}{dt}
        \label{eq3b}
        \end{align}
        !et


Result:

<!-- Equation labels as ordinary links -->
<div id="eq2b"></div>

$$
\begin{equation}
u(t)=e^{-at}
\label{eq2b} \tag{3}
\end{equation}
$$

<!-- Equation labels as ordinary links -->
<div id="eq3b"></div>

$$
\begin{equation}  
v(t) - 1 = \frac{du}{dt}
\label{eq3b} \tag{4}
\end{equation}
$$

We can refer to the last equations as the system [(3)](#eq2b)-[(4)](#eq3b).




**Test 5: Multiple, aligned equations without label.** In LaTeX,
equations within an `align` environment is automatically given numbers.
To ensure that an html document with MathJax gets the same equation numbers
as its latex/pdflatex companion, DocOnce generates labels in equations where
there is no label prescribed. For example,

        !bt
        \begin{align}
        u(t)&=e^{-at}
        \\
        v(t) - 1 &= \frac{du}{dt}
        \end{align}
        !et


is edited to something like

        !bt
        \begin{align}
        u(t)&=e^{-at}
        \label{_auto5}\\
        v(t) - 1 &= \frac{du}{dt}
        \label{_auto6}
        \end{align}
        !et


and the html output gets the two equation numbered.

<!-- Equation labels as ordinary links -->
<div id="_auto1"></div>

$$
\begin{equation}
u(t)=e^{-at}
\label{_auto1} \tag{5}
\end{equation}
$$

<!-- Equation labels as ordinary links -->
<div id="_auto2"></div>

$$
\begin{equation}  
v(t) - 1 = \frac{du}{dt}
\label{_auto2} \tag{6}
\end{equation}
$$

**Test 6: Multiple, aligned equations with multiple alignments.**
The `align` environment can be used with two `&` alignment characters, e.g.,

        !bt
        \begin{align}
        \frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L),
        \ t\in (0,T]\\
        u(0,t) &= u_0(x), & x\in [0,L]
        \end{align}
        !et


The result in ipynb becomes

<!-- Equation labels as ordinary links -->
<div id="_auto3"></div>

$$
\begin{equation}
\frac{\partial u}{\partial t} = \nabla^2 u,  x\in (0,L),
\ t\in (0,T]
\label{_auto3} \tag{7}
\end{equation}
$$

<!-- Equation labels as ordinary links -->
<div id="_auto4"></div>

$$
\begin{equation}  
u(0,t) = u_0(x),  x\in [0,L]
\label{_auto4} \tag{8}
\end{equation}
$$

A better solution is usually to use an `alignat` environment:

        !bt
        \begin{alignat}{2}
        \frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L),
        \ t\in (0,T]\\
        u(0,t) &= u_0(x), & x\in [0,L]
        \end{alignat}
        !et


with the rendered result

<!-- Equation labels as ordinary links -->
<div id="_auto5"></div>

$$
\begin{equation}
\frac{\partial u}{\partial t} = \nabla^2 u,  x\in (0,L),
\ t\in (0,T]
\label{_auto5} \tag{9}
\end{equation}
$$

<!-- Equation labels as ordinary links -->
<div id="_auto6"></div>

$$
\begin{equation}  
u(0,t) = u_0(x),  x\in [0,L]
\label{_auto6} \tag{10}
\end{equation}
$$

**align/alignat environments with equation numbers are anti-aligned!**

In the `sphinx`, `ipynb`, and `pandoc` output formats, DocOnce rewrites
the equations in an `alignat` environment as individual equations in
`equation` environments (or more precisely, `sphinx` can work with
`alignat*` so only numbered `alignat` equations get rewritten as individual
equations). If the alignment is somewhat important, try the best with a
manual rewrite in terms of separate `equation` environments, and stick to
`align*` and `alignat*` in `sphinx`.




If DocOnce had not do rewritten of the above equations, they would be
rendered in ipynb as

$$
\begin{equation}
\frac{\partial u}{\partial t} = \nabla^2 u,  x\in (0,L),
\ t\in (0,T]
\end{equation}
!et

<!-- Equation labels as ordinary links -->
<div id="_auto7"></div>

$$
\begin{equation}  
u(0,t) = u_0(x),  x\in [0,L]
\label{_auto7} \tag{11}
\end{equation}
$$
__Test 7: Multiple, aligned eqnarray equations without label.__ Let us
try the old `eqnarray*` environment.
!bc latexcod
!bt
\begin{eqnarray*}
u(t)&=& e^{-at}\\ 
v(t) - 1 &=& \frac{du}{dt}
\end{eqnarray*}
!et
!ec
which results in
!bt
\begin{eqnarray*}
u(t)&=& e^{-at}\\ 
v(t) - 1 &=& \frac{du}{dt}
\end{eqnarray*}
$$

**Test 8: Multiple, eqnarrayed equations with label.**
Here we use `eqnarray` with labels:

        !bt
        \begin{eqnarray*}
        u(t)&=& e^{-at}\\
        v(t) - 1 &=& \frac{du}{dt}
        \end{eqnarray*}
        !et


which results in

<!-- Equation labels as ordinary links -->
<div id="eq2c"></div> <div id="eq3c"></div>

$$
\begin{eqnarray}
u(t)&=& e^{-at} \label{eq2c} \tag{12}\\ 
v(t) - 1 &=& \frac{du}{dt} \label{eq3c} \tag{13}
\end{eqnarray}
$$

Can we refer to the last equations as the system [(12)](#eq2c)-[(13)](#eq3c)
in the ipynb format?

**Test 9: The `multiline` environment with label and number.**
The LaTeX code

        !bt
        \begin{eqnarray}
        u(t)&=& e^{-at}
        \label{eq2c}\\
        v(t) - 1 &=& \frac{du}{dt}
        \label{eq3c}
        \end{eqnarray}
        !et


gets rendered as

<!-- Equation labels as ordinary links -->
<div id="multiline:eq1"></div>

$$
\begin{multline}
\int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
f(a+(j+1)h)) \\ 
=\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
\label{multiline:eq1} \tag{14}
\end{multline}
$$

and we can hopefully refer to the Trapezoidal rule
as the formula [(14)](#multiline:eq1).


**Test 10: Splitting equations using a split environment.**
Although `align` can be used to split too long equations, a more obvious
command is `split`:

        !bt
        \begin{multline}
        \int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
        f(a+(j+1)h)) \\
        =\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
        \label{multiline:eq1}
        \end{multline}
        !et


The result becomes

<!-- Equation labels as ordinary links -->
<div id="_auto8"></div>

$$
\begin{equation}
\begin{split}
\int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
f(a+(j+1)h)) \\ 
=\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
\end{split}
\label{_auto8} \tag{15}
\end{equation}
$$

**Test 11: Newcommands and boldface bm vs pmb.**
First we use the plain old pmb package for bold math. The formula

        !bt
        \begin{equation}
        \begin{split}
        \int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
        f(a+(j+1)h)) \\
        =\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
        \end{split}
        \end{equation}
        !et


and the inline expression `$\nabla\pmb{u} (\pmb{x})\cdot\pmb{n}$`
(with suitable newcommands using pmb)
get rendered as

$$
\frac{\partial\pmb{u}}{\partial t} +
\pmb{u}\cdot\nabla\pmb{u} = \nu\nabla^2\pmb{u} -
\frac{1}{\varrho}\nabla p,
$$

and $\nabla\pmb{u} (\pmb{x})\cdot\pmb{n}$.

Somewhat nicer fonts may appear with the more modern `\bm` command:

        !bt
        \[ \frac{\partial\u}{\partial t} +
        \u\cdot\nabla\u = \nu\nabla^2\u -
        \frac{1}{\varrho}\nabla p,\]
        !et


(backslash `ubm` is a newcommand for bold math $u$), for which we get

$$
\frac{\partial\boldsymbol{u}}{\partial t} +
\boldsymbol{u}\cdot\nabla\boldsymbol{u} = \nu\nabla^2\boldsymbol{u} -
\frac{1}{\varrho}\nabla p.
$$

Moreover,

        !bt
        \[ \frac{\partial\ubm}{\partial t} +
        \ubm\cdot\nabla\ubm = \nu\nabla^2\ubm -
        \frac{1}{\varrho}\nabla p,\]
        !et


becomes $\nabla\boldsymbol{u}(\boldsymbol{x})\cdot\boldsymbol{n}$.

**Warning.**

Note: for the ipynb format, `\bm` was substituted by DocOnce
to `\boldsymbol`.





**Problematic equations.**
Finally, we collect some problematic formulas in MathJax. They all work
fine in LaTeX.

        $\nabla\boldsymbol{u}(\boldsymbol{x})\cdot\boldsymbol{n}$


results in

$$
{\color{blue}\frac{\partial\pmb{u}}{\partial t}} +
\nabla\cdot\nabla\pmb{u} = \nu\nabla^2\pmb{u} -
\frac{1}{\varrho}\nabla p,
$$

but correct rendering in sphinx requires omitting the `\color` command.

Sometimes one must be extra careful with the LaTeX syntax to get sphinx MathJax
to render a formula correctly. Consider the combination of a bar over a
bold math symbol:

        !bt
        \[ {\color{blue}\frac{\partial\u}{\partial t}} +
        \nabla\cdot\nabla\u = \nu\nabla^2\u -
        \frac{1}{\varrho}\nabla p,\]
        !et


which for ipynb output results in

$$
\bar\boldsymbol{f} = f_c^{-1}\boldsymbol{f}.
$$

With sphinx, this formula is not rendered. However, using curly braces for the bar,

        !bt
        \[ \bar\f = f_c^{-1}\f,\]
        !et


makes the output correct also for sphinx:

$$
\bar{\boldsymbol{f}} = f_c^{-1}\boldsymbol{f},
$$

**Matrix Environment.**
Nested environments with labled pmatrix environments cause wired representation in ipynb and html.

        !bt
        \[ \bar{\f} = f_c^{-1}\f,\]
        !et


which becomes

<!-- Equation labels as ordinary links -->
<div id="_auto9"></div>

$$
\begin{equation}
\begin{pmatrix}
G_2 + G_3  -G_3  -G_2  0 
\label{_auto9} \tag{16}
\end{equation}
$$

<!-- Equation labels as ordinary links -->
<div id="_auto10"></div>

$$
\begin{equation}  
-G_3  G_3 + G_4  0  -G_4 
\label{_auto10} \tag{17}
\end{equation}
$$

<!-- Equation labels as ordinary links -->
<div id="_auto11"></div>

$$
\begin{equation}  
-G_2  0  G_1 + G_2  0 
\label{_auto11} \tag{18}
\end{equation}
$$

<!-- Equation labels as ordinary links -->
<div id="_auto12"></div>

$$
\begin{equation}  
0  -G_4  0  G_4
\end{pmatrix}
=
\begin{pmatrix}
v_1 
\label{_auto12} \tag{19}
\end{equation}
$$

<!-- Equation labels as ordinary links -->
<div id="_auto13"></div>

$$
\begin{equation}  
v_2 
\label{_auto13} \tag{20}
\end{equation}
$$

<!-- Equation labels as ordinary links -->
<div id="_auto14"></div>

$$
\begin{equation}  
v_3 
\label{_auto14} \tag{21}
\end{equation}
$$

<!-- Equation labels as ordinary links -->
<div id="_auto15"></div>

$$
\begin{equation}  
v_4
\end{pmatrix}
+ \cdots 
\label{_auto15} \tag{22}
\end{equation}
$$

<!-- Equation labels as ordinary links -->
<div id="_auto16"></div>

$$
\begin{equation}  
\begin{pmatrix}
C_5 + C_6  -C_6  0  0 
\label{_auto16} \tag{23}
\end{equation}
$$

<!-- Equation labels as ordinary links -->
<div id="_auto17"></div>

$$
\begin{equation}  
-C_6  C_6  0  0 
\label{_auto17} \tag{24}
\end{equation}
$$

<!-- Equation labels as ordinary links -->
<div id="_auto18"></div>

$$
\begin{equation}  
0  0  0  0 
\label{_auto18} \tag{25}
\end{equation}
$$

<!-- Equation labels as ordinary links -->
<div id="_auto19"></div>

$$
\begin{equation}  
0  0  0  0
\end{pmatrix}
\frac{d}{dt} =
\begin{pmatrix}
v_1 
\label{_auto19} \tag{26}
\end{equation}
$$

<!-- Equation labels as ordinary links -->
<div id="_auto20"></div>

$$
\begin{equation}  
v_2 
\label{_auto20} \tag{27}
\end{equation}
$$

<!-- Equation labels as ordinary links -->
<div id="_auto21"></div>

$$
\begin{equation}  
v_3 
\label{_auto21} \tag{28}
\end{equation}
$$

<!-- Equation labels as ordinary links -->
<div id="_auto22"></div>

$$
\begin{equation}  
v_4
\end{pmatrix} =
\begin{pmatrix}
0 
\label{_auto22} \tag{29}
\end{equation}
$$

<!-- Equation labels as ordinary links -->
<div id="_auto23"></div>

$$
\begin{equation}  
0 
\label{_auto23} \tag{30}
\end{equation}
$$

<!-- Equation labels as ordinary links -->
<div id="_auto24"></div>

$$
\begin{equation}  
0 
\label{_auto24} \tag{31}
\end{equation}
$$

<!-- Equation labels as ordinary links -->
<div id="_auto25"></div>

$$
\begin{equation}  
-i_0
\end{pmatrix}
\label{_auto25} \tag{32}
\end{equation}
$$

The same matrices without labels seem to translate better:

        !bt
        \begin{align}
        \begin{pmatrix}
        G_2 + G_3 & -G_3 & -G_2 & 0 \\
        -G_3 & G_3 + G_4 & 0 & -G_4 \\
        -G_2 & 0 & G_1 + G_2 & 0 \\
        0 & -G_4 & 0 & G_4
        \end{pmatrix}
        &=
        \begin{pmatrix}
        v_1 \\
        v_2 \\
        v_3 \\
        v_4
        \end{pmatrix}
        + \cdots \\
        \begin{pmatrix}
        C_5 + C_6 & -C_6 & 0 & 0 \\
        -C_6 & C_6 & 0 & 0 \\
        0 & 0 & 0 & 0 \\
        0 & 0 & 0 & 0
        \end{pmatrix}
        \frac{d}{dt} &=
        \begin{pmatrix}
        v_1 \\
        v_2 \\
        v_3 \\
        v_4
        \end{pmatrix} =
        \begin{pmatrix}
        0 \\
        0 \\
        0 \\
        -i_0
        \end{pmatrix}
        \end{align}
        !et


which becomes

$$
\begin{pmatrix}
G_2 + G_3  -G_3  -G_2  0
$$

$$
-G_3  G_3 + G_4  0  -G_4
$$

$$
-G_2  0  G_1 + G_2  0
$$

$$
0  -G_4  0  G_4
\end{pmatrix}
=
\begin{pmatrix}
v_1
$$

$$
v_2
$$

$$
v_3
$$

$$
v_4
\end{pmatrix}
+ \cdots
$$

$$
\begin{pmatrix}
C_5 + C_6  -C_6  0  0
$$

$$
-C_6  C_6  0  0
$$

$$
0  0  0  0
$$

$$
0  0  0  0
\end{pmatrix}
\frac{d}{dt} =
\begin{pmatrix}
v_1
$$

$$
v_2
$$

$$
v_3
$$

$$
v_4
\end{pmatrix} =
\begin{pmatrix}
0
$$

$$
0
$$

$$
0
$$

$$
-i_0
\end{pmatrix}
$$

aaf4036a48635f4f3b840181573f1b69c6faa46e
ipynb
Jupyter Notebook
doc/pub/mathjax/.ipynb_checkpoints/math_test-checkpoint.ipynb
dutille/doconce
f1d41ae065f7d3c24450180c2ce019b03edbaddc
BSD-3-Clause
2015-01-07T06:57:14.000Z
2022-02-16T01:45:25.000Z
doc/pub/mathjax/.ipynb_checkpoints/math_test-checkpoint.ipynb
dutille/doconce
f1d41ae065f7d3c24450180c2ce019b03edbaddc
BSD-3-Clause
2015-01-08T11:03:26.000Z
2020-12-17T12:54:46.000Z
doc/pub/mathjax/.ipynb_checkpoints/math_test-checkpoint.ipynb
dutille/doconce
f1d41ae065f7d3c24450180c2ce019b03edbaddc
BSD-3-Clause
2015-03-19T17:17:34.000Z
2022-01-02T15:45:20.000Z
Qwen/Qwen-72B
1. YES
2. YES