Mathematical equations

LaTeX

The syntax for writing equations is LaTeX. See some examples below.

LaTeX has a steep learning curve, so you may want to check online documentation, for example https://www.overleaf.com/learn/latex/Mathematical_expressions.

MathJax

In Sphinx, the rendering (display) of the equations can be done in different ways, that won’t be discussed here.

The selected option is to use the sphinx.ext.mathjax extension. This extension uses the JavaScript package MathJax to transform the LaTeX markup to readable math live in the browser.

The mathjax_path in the conf.py file indicates where the MathJax library resides.

By default, this is the MathJax site, but the path can be changed cross-site scripting is NOT allowed.

Equation editors

Given that LaTeX syntax may be daunting, a WYSIWYG math editor can be useful, or at least an interactive previewer like https://www.latex4technics.com/.

Math examples

Code:

If :math:`\sigma_{1}` equals :math:`\sigma_{2}` then etc, etc.

Output:

If \(\sigma_{1}\) equals \(\sigma_{2}\) then etc, etc.

Code:

:math:`\underline{x}=[  x_{1}, ...,  x_{n}]^{T}`

Output:

\(\underline{x}=[ x_{1}, ..., x_{n}]^{T}\)

Code:

\langle \alpha, \beta  \rangle
\in
\Biggl \lbrace
{
M,\text{ if }
   {
    l(\underline{x}) =
      \frac { p(\underline{x}|M ) } { p(\underline{x}|U) }
      \geq
       \frac { p(U) }{ p(M) } }
\atop
U, \text{ otherwise }
}

Output:

\[\langle \alpha, \beta \rangle \in \Biggl \lbrace { M,\text{ if } { l(\underline{x}) = \frac { p(\underline{x}|M ) } { p(\underline{x}|U) } \geq \frac { p(U) }{ p(M) } } \atop U, \text{ otherwise } }\]

How to label and cross-reference equations in reStructuredText

• To add a label to an equation in reST, use the :label: option inside the .. math:: directive.

  Code:

  .. math::
     :label: euler-identity
  
     e^{i\pi} + 1 = 0
  

  Output:

  (1)\[e^{i\pi} + 1 = 0\]

• Once labeled, you can reference the equation anywhere in your documentation using the Sphinx :eq: role.

  Code:

  As shown in equation :eq:`euler-identity`,
  the relationship between the fundamental mathematical constants is elegant.
  

  Output:

  As shown in equation (1), the relationship between the fundamental mathematical constants is elegant.

By default, Sphinx only numbers equations that have a label attached to them. If you want Sphinx to assign a number to every block equation in your documentation (even the ones you haven’t labeled), you can add this line to your conf.py:

math_number_all = True

Warning

Technically, the numbering of equations does not use the same numbering engine as the numbering of tables, figures, and code-blocks.

For equations, one must use the :label: option and the :eq: role.

For tables and figures, one must use the :name: option and the :numref: role.

It is how it is…

Links