DP Notes (document title)

Handling Equations

General information about using TeX to write equations is given in [https://www.overleaf.com/learn/latex/Aligning_equations_with_amsmath]. A document that includes proper equations with bold non-italic for vector/matrix symbols is shelltypes.rst. Equation labeling follows the convention of <eq-docName-N>, for example, eq-shelltypes-12 in file shelltypes.rst.

We obtain an inline math expression using the math directive as \(y = f(x)\). If we define math as the default role, then we do not need to precede each math directive with “:math:”. A math expression can be defined once at the top of the document (as for \(\hat{\mathbf{n}}_\mathbf{c}\)), and then placed within bars in a paragraph or table. Such a math expression cannot be used within an equation. The standard way to do this in TeX is to define the expression as a command, and then use this command in the equation; we have not worked out how to do this within the Sphinx system.

Typesetting Scalars and Vectors/Matrices

The mathbf-command operates on letters, numbers and upper-case Greek letters. The pmb-command (Poor Man’s Bold) and boldsymbol-command operate on lower-case Greek letters, and to make them non-italic we must insert their UTF-8 encoding. The boldsymbol-command produces a better image than the pmb-command. The hat- and dot-commands typically operate on a single character.

Scalars are typeset in italic \((x, \sigma)\), while vectors/matrices are typeset in non-italic bold \(( \mathbf{x}, \mathbf{ E }_m, \mathbf{ σ } \textrm{ or with bracket notation } \left\{ \mathbf{ σ } \right\} )\).

Scalars use non-bold, italic characters (standard TeX): \(( x, \sigma_{yy} )\).

Vectors/matrices use (1) bold non-italic regular characters (prefer mathbf{}): \(\{ {\mathbf E}_m, {\bf E}_m \}\); (2) bold non-italic Greek symbols (prefer mathbf{} with UTF-8 encoding copied directly into the RST file): \(\{ \mathbf{σ}_m, \pmb{σ}_m, \boldsymbol{σ}_m \}\); and rarely (3) bold italic Greek symbols (prefer boldsymbol{}): \(\{ {\boldsymbol\sigma}_m, {\pmb\sigma}_m, {\mathbf\sigma}_m, \sigma_m \}\).

Equation Examples

(1)\[\begin{split}\begin{split} A &= \frac{\pi r^2}{2} \\[12pt] &= \frac{1}{2} \pi r^2 \end{split}\end{split}\]

We see in Eq. (1) that the name of the game is Scrabble.

The following equation contains commonly used symbols to denote scalar and vector quantities (it is not yet typeset in the preferred fashion described above):

(2)\[\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{θ}_\mathbf{b} \} \end{array}\end{split}\]

A typical left-aligned equation using a “with” expression is given here:

(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}\]

A typical equation that contains “(2D model: expr)”:

(4)\[ \begin{align}\begin{aligned}y = f(x) \quad \left( \mbox{2D model: } x = 2 \right).\\\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} \]

Case Statement

The following equation demonstrates how to create a case statement with TeX (using the cases construct) and with LaTeX (using the array construct). Note the use of hfill to get right-alignment of the first column with the cases construct. The column alignment for the array construct is specified by the arguments after the begin-array term. For the array construct, the dot following the right term gives us no right delimiter.

(5)\[\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}\]

Handling Commands and Other Things

We can refer to an equation using the eq-directive as in Eq. (6) is given above. We can refer to a command with the cmd-directive as in: model calm does a neat thing. We can refer to a FISH function with the func-directive as in the FISH function measure.list does a cool thing. We can refer to the command without linking to the command description using the lcmd-directive as in model calm. We can refer to the FISH function or variable without linking to the function or variable descriptions using the sym-directive as in measure.list and myVar.

We can refer to an integer argument with the int-directive, and the argument value with the lint-directive as in this command takes an integer argument i that may have a value of 3. The same convention applies to other types as well, such as bool, int, flt, vec, etc. For example, a vector argument v may take the value of f, and a string argument s may take the value of fred.

We can insert a flagged remark into the text using the directives flag, flag2 and flag3. The flag-directive adds the remark in red text. The flag2-directive marks a block of text, it is not marked in the output document. The flag3-directive adds a comment for internal review, it does not appear in the output document.

We can refer to a marked location in another document using the ref-directive. (1) Material Modeling Support Package puts in the link and the name of that section. (2) mat sup puts in the link and the word “mat sup”.