Math

Firstly, math of all kinds is written in LaTex markup. See User’s Guide for the amsmath Package (LaTex math)(PDF) for reference. Additional utility links appear in Resources for Working with Math below.

Offset Equations

Math that is offset (centered, indented, and on its own line) is created with the .. math:: directive

(1)\[ x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}\]

(2)\[\textrm{when} \ \ ax^2 + bx + c = 0\]

Offset Equations
++++++++++++++++

Math that is offset (centered, indented, and on its own line) is created
with the ``.. math::`` directive

.. math::
   :label: spmath-eqoffset-lbl

    x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}

.. math::
   :name: spmath-eqoffset-nm

   \textrm{when} \ \ ax^2 + bx + c = 0

Inline Equations

Inline equations, such as \(a^2 + b^2 = c^2\) or \(E = mc^2\) or simple reference to values (e.g., \(\rho\)) are achieved through the :math: role or, in shorthand, simply placing the matter between tick marks ( ` ` ).

Inline equations, such as :math:`a^2 + b^2 = c^2` or `E = mc^2` or simple
reference to values (e.g., `\rho`) are achieved through the ``:math:`` role
or, in shorthand, simply placing the matter between tick marks ( ` ` ).

Links

In addition to the usual use of :name: option on the .. math:: directive, there is a second method of declaring an anchor on an equation—the :label: option, which can be accessed via links built with the :eq: role. Both are illustrated in (1) and (2) above. Either anchor construction, if used, will cause the equation to be numbered at the right end of the equation line. When neither are present offset equations aren’t numbered.

The difference between the two is that links to the :name: construction cannot recover the equation number so the link label must be declared explicitly as in Equation (2) above. Links to the :label: construction, such as Equation (1) above, will implicitly use the equation number as a link label (note the word “Equation” preceding the number must appear outside the role).

The difference between the two is that links to the ``:name:`` construction
cannot recover the equation number so the link label must be declared
explicitly :ref:`as in Equation (2) above <spmath-eqoffset-nm>`. Links to
the ``:label:`` construction, such as Equation :eq:`spmath-eqoffset-lbl`
above, will implicitly use the equation number as a link label (note the
word "Equation" preceding the number must appear *outside* the role).

ICG Usage

There is no standard for numbering equations at the moment. Mostly (though not uniformly), equations are only numbered if there will be need to refer to them elsewhere. With regard to anchor construction, generally the :label: form is preferred, but again, there is no standard and both :label: and :name: are used.

Some Math & LaTeX & MathJax Tips and Tricks

De-italicize Roman Characters

Use textrm{text}. Compare

\[E_m\ =\ 10^{{RMR - 10} \over {40}}\]

.. math::

   E_m\ =\ 10^{{RMR - 10} \over {40}}

\[E_m\ =\ 10^{{\textrm{RMR} - 10} \over {40}}\]

.. math::

   E_m\ =\ 10^{{\textrm{RMR} - 10} \over {40}}

Other typeface variances

\[ \begin{align}\begin{aligned}\begin{split} \begin{array}{c} \{ x, x_c, \mathbf{x}, \mathbf{x_c}, \dot{\mathbf{x}}_\mathbf{c}, \hat{\mathbf{n}}_\mathbf{c} \} \\ \{ \dot{\mathbf{x}}_\mathbf{c}^{(b)}, \pmb{ω}^{(b)} \} \\ \{ \delta, \theta, \delta_s, \theta_b, \pmb{ω}, \pmb{δ}, \pmb{θ}, \pmb{δ}_\mathbf{s}, \pmb{\theta}_\mathbf{b} \} \end{array}\end{split}\\.. sourcecode:: text\\ .. math::\\\begin{split} \begin{array}{c} \{ x, x_c, \mathbf{x}, \mathbf{x_c}, \dot{\mathbf{x}}_\mathbf{c}, \hat{\mathbf{n}}_\mathbf{c} \} \\ \{ \dot{\mathbf{x}}_\mathbf{c}^{(b)}, \pmb{ω}^{(b)} \} \\ \{ \delta, \theta, \delta_s, \theta_b, \pmb{ω}, \pmb{δ}, \pmb{θ}, \pmb{δ}_\mathbf{s}, \pmb{\theta}_\mathbf{b} \} \end{array}\end{split}\end{aligned}\end{align} \]

Use:

• \mathbf for bold Roman characters

• \pmb for bold Greek characters

• de-italicize Greek characters by direct unicode insertion (see theta at the end of the array above)

More Fancy Spacing/Alignment

These will not be explained, but are left here as visual examples of some trickier arrangements. View the source of this page to copy the constructs.

(3)\[\begin{split}\begin{array}{l} y = f(x),\quad z = g(F_n) \\[3mm] \mbox{with }\quad x = 27 \\ \hskip{12mm} F_n = 34 \end{array}\end{split}\]

(4)\[y = f(x) \quad \left( \mbox{2D model: } x = 2 \right).\]

(5)\[ \begin{align}\begin{aligned}y = f(x)\\\begin{split}\mathbf{M^r} = \left\{ \begin{array}{l} {\qquad \mathbf{M^r},\qquad \left\| \mathbf{M^{r}} \right\| \le M^{*} } \\ {\qquad M^{*} \left( \mathbf{M^r} / \left\| \mathbf{M^{r}} \right\| \right),\qquad {\rm otherwise.}} \end{array} \right.\end{split}\\\begin{split}s_r = \left\{ \begin{array}{l} {\qquad {\rm true},\qquad \left\| \mathbf{M^{r}} \right\| =M^{*} } \\ {\qquad {\rm false},\qquad {\rm otherwise.}} \end{array} \right.\end{split}\end{aligned}\end{align} \]

(6)\[\begin{split}|x| = \cases{ \hfill x, & if $x > 0$; \cr -x, & otherwise. \cr} = \left\{ \begin{array}{rl} x, & \mbox{if $x > 0$;} \\ -x, & \mbox{otherwise.} \end{array} \right.\end{split}\]

Old Usages that Don’t Work

Carriage returns

BAD: \cr
GOOD: \\

Alignment

BAD: \eqalign
GOOD: \begin{align} ... \end{align}

Resources for Working with Math

Docutils: Math Directive and Math Role

Sphinx: Math

Utility: Online equation builder