13. Math, Code Formatting and Execution#

13.1. Math#

There are multiple ways one can include mathematical expressions in MyST-Markdown.

13.1.1. Sphinx role/directive#

One is using the math role or directive from sphinx to create inline and block math:

Let {math}`f(x_1,x_2)` represent our objective function.
```{math}
:label: problem_1
\min_{x_1,x_2} \quad& f(x_1,x_2) \\
\text{s.t.} \quad& x_1\geq 0 \\
& x_2 \geq 0 \\
& x_1+x_2 \leq 0
```
The label option lets you refer to {eq}`problem_1`.

will result in:

Let $f(x_1,x_2)$ represent our objective function.

(13.1)#\[\begin{split}\min_{x_1,x_2} \quad& f(x_1,x_2) \\ \text{s.t.} \quad& x_1\geq 0 \\ & x_2 \geq 0 \\ & x_1+x_2 \leq 0\end{split}\]

The label option lets you refer to (13.1).

13.1.2. LaTeX-style math#

Having enabled amsmath in _config.yml, one can also use the math environments

equation, multline, gather, align, alignat, flalign, matrix, pmatrix, bmatrix, Bmatrix, vmatrix, Vmatrix, eqnarray

and the unnumbered equivalents with *.

Warning

\labels inside these environments may not work properly, so if you’d like to refer to equations, prefer the directive described above. For multiple labels in the same environment, make sure you read Having multiple labels in equations.

Attention

Avoid using $$ for math environments, in my random testing it didn’t work well sometimes.

13.1.3. Mathematical Statements#

For formatting mathematical text like definitions and proofs, the sphinx-proof package is used. This package defines a number of additional directives, such as {prf:proof} and {prf:algorithm}. Check the website for a complete list.

```{prf:algorithm} Barrier method for LP
:label: p1c7:alg:barrier_method

**initialise.** (primal-dual feasible) $(x^0, p^0, u^0)$, $\epsilon > 0$, $\mu_0 = \mu_1>0$,

$\beta \in (0,1)$, $k = 0$. 

**while** $n \mu_k > \epsilon$

compute $d^{k+1} = (d_x^{k+1}, d_p^{k+1}, d_u^{k+1})$

compute appropriate step size $\theta^{k+1} = (\theta_p^{k+1}, \theta_d^{k+1}$)

$(x^{k+1}, p^{k+1}, u^{k+1}) = (x^k, p^k, u^k) + \theta^{k+1}d^{k+1}$

$k = k+1$

$\mu_{k+1} = \beta\mu_k$

**end while**

**return** $(x^k, p^k, u^k)$.
```

Algorithm 13.1 (Barrier method for LP)

initialise. (primal-dual feasible) $(x^0, p^0, u^0)$, $\epsilon > 0$, $\mu_0 = \mu_1>0$,
$\beta \in (0,1)$, $k = 0$.
while $n \mu_k > \epsilon$
1. compute $d^{k+1} = (d_x^{k+1}, d_p^{k+1}, d_u^{k+1})$ using $\eqref{p1c7:eq:infeasible_perturbed_system}$
2. compute appropriate step size $\theta^{k+1} = (\theta_p^{k+1}, \theta_d^{k+1}$)
3. $(x^{k+1}, p^{k+1}, u^{k+1}) = (x^k, p^k, u^k) + \theta^{k+1}d^{k+1}$
4. $k = k+1$
5. $\mu_{k+1} = \beta\mu_k$
end while
return $(x^k, p^k, u^k)$.

When using this package and compiling a PDF, sphinx-proof seems to automatically add a proof index at the end. I disabled it in the template by adding to the config latex_domain_indices: false , but it can be enabled back if desired.

13.2. Code#

13.2.1. Formatted Code#

Syntax highlighting is simple:

```python
import numpy as np
a = np.random.random()
```

gives

import numpy as np
a = np.random.random()

You can even have nice synced tabs like this:

Julia

function square_list(l)
    l .^ 2
end

Python

def square_list(l):
    return [x**2 for x in l]

Julia

function add_one(x)
    x+1
end

Python

def add_one(x):
    return x+1

Look at the Markdown file of this page to see how.

13.2.2. Executable Code#

Attention

If you want to execute code, you need to add a MyST-Markdown top-matter to the source file, or use a .ipynb file. You can do so easily with

jupyter-book myst init mymarkdownfile.md --kernel kernelname

If you don’t know the kernel name, you can list them with

jupyter kernelspec list

Code to be executed should be included in {code-cell}s.

```{code-cell}
1+1
```

gives

1+1

Important

While we are working with Markdown files, at the end of the day these are executed while being interpreted as notebooks. Thus, you can only have one kernel associated with a file, which is defined in the top-matter. One cannot execute Python code in one block and Julia in another in the same file.

There are also lots of options to work with code-cells, such as hiding the input, making cells scrollable, and formatting the outputs. You can read more here.

Note

One thing I encountered while preparing this was that when working with Julia, if you create some files but then update Julia version, one may need to rebuild IJulia to get things working again.

13.3. Further reading#

Math pages from Jupyter Book, MyST-Markdown, and Sphinx.
More on syntax highlighting, including numbering and highlighting lines, including code from files and inline highlighting.