# Syntax Guide¶

Note

This documentation utilized the Markedly Structured Text (MyST) syntax.

This package utilizes a Sphinx domain - named “proof” - to describe and link typeset markup objects (theorems, proofs, corollaries, etc.) which we think belong together. All directives follow the pattern `{<domain_name>:<typeset>}`

while all the roles follow the pattern `{<domain_name>:ref}`

. To utilize any directive in the `proof`

domain follow the pattern `{prf:<typeset>}`

. To reference any directive follow the pattern `{prf:ref}`

.

## Collection of Directives¶

### Proofs¶

A proof directive can be included using the `prf:proof`

pattern. Unlike the other directives provided through this extension, a proof directive does not include any parameters nor does it require any arguments. A proof directive can easily be referenced through targets.

The following option is supported:

`class`

: textValue of the proof’s class attribute which can be used to add custom CSS or JavaScript.

**Example**

Proof. We’ll omit the full proof.

But we will prove sufficiency of the asserted conditions.

To this end, let \(y \in \mathbb R^n\) and let \(S\) be a linear subspace of \(\mathbb R^n\).

Let \(\hat y\) be a vector in \(\mathbb R^n\) such that \(\hat y \in S\) and \(y - \hat y \perp S\).

Let \(z\) be any other point in \(S\) and use the fact that \(S\) is a linear subspace to deduce

Hence \(\| y - z \| \geq \| y - \hat y \|\), which completes the proof.

**MyST Syntax**

```
````{prf:proof}
We'll omit the full proof.
But we will prove sufficiency of the asserted conditions.
To this end, let $y \in \mathbb R^n$ and let $S$ be a linear subspace of $\mathbb R^n$.
Let $\hat y$ be a vector in $\mathbb R^n$ such that $\hat y \in S$ and $y - \hat y \perp S$.
Let $z$ be any other point in $S$ and use the fact that $S$ is a linear subspace to deduce
```{math}
\| y - z \|^2
= \| (y - \hat y) + (\hat y - z) \|^2
= \| y - \hat y \|^2 + \| \hat y - z \|^2
```
Hence $\| y - z \| \geq \| y - \hat y \|$, which completes the proof.
````
```

*Source:* QuantEcon

### Theorems¶

A theorem directive can be included using the `prf:theorem`

pattern. The directive is enumerated by default and can take in an optional title argument. The following options are also supported:

`label`

: textA unique identifier for your theorem that you can use to reference it with

`{prf:ref}`

. Cannot contain spaces or special characters.`class`

: textValue of the theorem’s class attribute which can be used to add custom CSS or JavaScript.

`nonumber`

: flag (empty)Turns off theorem auto numbering.

\[\DeclareMathOperator*{\argmax}{arg\,max} \DeclareMathOperator*{\argmin}{arg\,min}\]

**Example**

(Orthogonal-Projection-Theorem)

Given \(y \in \mathbb R^n\) and linear subspace \(S \subset \mathbb R^n\), there exists a unique solution to the minimization problem

The minimizer \(\hat y\) is the unique vector in \(\mathbb R^n\) that satisfies

\(\hat y \in S\)

\(y - \hat y \perp S\)

The vector \(\hat y\) is called the **orthogonal projection** of \(y\) onto \(S\).

**MyST Syntax**

```
````{prf:theorem} Orthogonal-Projection-Theorem
:label: my-theorem
Given $y \in \mathbb R^n$ and linear subspace $S \subset \mathbb R^n$,
there exists a unique solution to the minimization problem
```{math}
\hat y := \argmin_{z \in S} \|y - z\|
```
The minimizer $\hat y$ is the unique vector in $\mathbb R^n$ that satisfies
* $\hat y \in S$
* $y - \hat y \perp S$
The vector $\hat y$ is called the **orthogonal projection** of $y$ onto $S$.
````
```

*Source:* QuantEcon

#### Referencing Theorems¶

You can refer to a theorem using the `{prf:ref}`

role like: `{prf:ref}`my-theorem` `

, which will replace the reference with the theorem number like so: Theorem 1. When an explicit text is provided, this caption will serve as the title of the reference. For example, `{prf:ref}`Orthogonal-Projection-Theorem <my-theorem>` `

will produce: Orthogonal-Projection-Theorem.

### Axioms¶

An axiom directive can be included using the `prf:axiom`

pattern. The directive is enumerated by default and can take in an optional title argument. The following options are also supported:

`label`

: textA unique identifier for your axiom that you can use to reference it with

`{prf:ref}`

. Cannot contain spaces or special characters.`class`

: textValue of the axiom’s class attribute which can be used to add custom CSS or JavaScript.

`nonumber`

: flag (empty)Turns off axiom auto numbering.

**Example**

\(\mathbb{R}\))

(Completeness ofEvery Cauchy sequence on the real line is convergent.

**MyST Syntax**

```
```{prf:axiom} Completeness of $\mathbb{R}$
:label: my-axiom
Every Cauchy sequence on the real line is convergent.
```
```

*Source:* [Sta09]

### Lemmas¶

A lemma directive can be included using the `prf:lemma`

pattern. The directive is enumerated by default and can take in an optional title argument. The following options are also supported:

`label`

: textA unique identifier for your lemma that you can use to reference it with

`{prf:ref}`

. Cannot contain spaces or special characters.`class`

: textValue of the lemma’s class attribute which can be used to add custom CSS or JavaScript.

`nonumber`

: flag (empty)Turns off lemma auto numbering.

**Example**

**MyST Syntax**

```
````{prf:lemma}
:label: my-lemma
If $\hat P$ is the fixed point of the map $\mathcal B \circ \mathcal D$ and $\hat F$ is the robust policy as given in [(7)](https://python-advanced.quantecon.org/robustness.html#equation-rb-oc-ih), then
```{math}
:label: rb_kft
K(\hat F, \theta) = (\theta I - C'\hat P C)^{-1} C' \hat P (A - B \hat F)
```
````
```

*Source:* QuantEcon

### Definitions¶

A definition directive can be included using the `prf:definition`

pattern. The directive is enumerated by default and can take in an optional title argument. The following options are also supported:

`label`

: textA unique identifier for your definition that you can use to reference it with

`{prf:ref}`

. Cannot contain spaces or special characters.`class`

: textValue of the definition’s class attribute which can be used to add custom CSS or JavaScript.

`nonumber`

: flag (empty)Turns off definition auto numbering.

**Example**

The *economical expansion problem* (EEP) for
\((A,B)\) is to find a semi-positive \(n\)-vector \(p>0\)
and a number \(\beta\in\mathbb{R}\), such that

**MyST Syntax**

```
````{prf:definition}
:label: my-definition
The *economical expansion problem* (EEP) for
$(A,B)$ is to find a semi-positive $n$-vector $p>0$
and a number $\beta\in\mathbb{R}$, such that
$$
&\min_{\beta} \hspace{2mm} \beta \\
&\text{s.t. }\hspace{2mm}Bp \leq \beta Ap
$$
````
```

*Source:* QuantEcon

#### Referencing Definitions¶

You can refer to a definition using the `{prf:ref}`

role like: `{prf:ref}`my-definition` `

, which will replace the reference with the definition number like so: Definition 1. When an explicit text is provided, this caption will serve as the title of the reference.

### Criteria¶

A criterion directive can be included using the `prf:criterion`

pattern. The directive is enumerated by default and can take in an optional title argument. The following options are also supported:

`label`

: textA unique identifier for your criterion that you can use to reference it with

`{prf:ref}`

. Cannot contain spaces or special characters.`class`

: textValue of the criterion’s class attribute which can be used to add custom CSS or JavaScript.

`nonumber`

: flag (empty)Turns off criterion auto numbering.

**Example**

(Weyl’s criterion)

Weyl’s criterion states that the sequence \(a_n\) is equidistributed modulo \(1\) if and only if for all non-zero integers \(m\),

**MyST Syntax**

```
````{prf:criterion} Weyl's criterion
:label: weyls-criterion
Weyl's criterion states that the sequence $a_n$ is equidistributed modulo $1$ if
and only if for all non-zero integers $m$,
```{math}
\lim_{n \rightarrow \infty} \frac{1}{n} \sum_{j=1}^{n} \exp^{2 \pi i m a_j} = 0
```
````
```

*Source:* Wikipedia

#### Referencing Criteria¶

You can refer to a criterion using the `{prf:ref}`

role like: `{prf:ref}`weyls-criterion` `

, which will replace the reference with the criterion number like so: Criterion 1. When an explicit text is provided, this caption will serve as the title of the reference.

### Remarks¶

A remark directive can be included using the `prf:remark`

pattern. The directive is enumerated by default and can take in an optional title argument. The following options are also supported:

`label`

: textA unique identifier for your remark that you can use to reference it with

`{prf:ref}`

. Cannot contain spaces or special characters.`class`

: textValue of the remark’s class attribute which can be used to add custom CSS or JavaScript.

`nonumber`

: flag (empty)Turns off remark auto numbering.

**Example**

More generally there is a class of density functions that possesses this feature, i.e.

This property is called **spherical symmetry** (see p 81. in Leamer
(1978))

**MyST Syntax**

```
```{prf:remark}
:label: my-remark
More generally there is a class of density functions
that possesses this feature, i.e.
$$
\exists g: \mathbb{R}_+ \mapsto \mathbb{R}_+ \ \ \text{ and } \ \ c \geq 0,
\ \ \text{s.t. the density } \ \ f \ \ \text{of} \ \ Z \ \
\text{ has the form } \quad f(z) = c g(z\cdot z)
$$
This property is called **spherical symmetry** (see p 81. in Leamer
(1978))
```
```

*Source:* QuantEcon

### Conjectures¶

**Example**

\(\gamma\) conjecture)

(FakeThis is a dummy conjecture to illustrate that one can use math in titles.

**MyST Syntax**

```
```{prf:conjecture} Fake $\gamma$ conjecture
:label: my-conjecture
This is a dummy conjecture to illustrate that one can use math in titles.
```
```

#### Referencing Conjectures¶

You can refer to a conjecture using the `{prf:ref}`

role like: `{prf:ref}`my-conjecture` `

, which will replace the reference with the conjecture number like so: Conjecture 1. When an explicit text is provided, this caption will serve as the title of the reference.

### Corollaries¶

A corollary directive can be included using the `prf:corollary`

pattern. The directive is enumerated by default and can take in an optional title argument. The following options are also supported:

`label`

: textA unique identifier for your corollary that you can use to reference it with

`{prf:ref}`

. Cannot contain spaces or special characters.`class`

: textValue of the corollary’s class attribute which can be used to add custom CSS or JavaScript.

`nonumber`

: flag (empty)Turns off corollary auto numbering.

**Example**

If \(A\) is a convergent matrix, then there exists a matrix norm such that \(\vert \vert A \vert \vert < 1\).

**MyST Syntax**

```
```{prf:corollary}
:label: my-corollary
If $A$ is a convergent matrix, then there exists a matrix norm such
that $\vert \vert A \vert \vert < 1$.
```
```

*Source:* QuantEcon

#### Referencing Corollaries¶

You can refer to a corollary using the `{prf:ref}`

role like: `{prf:ref}`my-corollary` `

, which will replace the reference with the corollary number like so: Corollary 1. When an explicit text is provided, this caption will serve as the title of the reference.

### Algorithms¶

An algorithm directive can be included using the `prf:algorithm`

pattern. The directive is enumerated by default and can take in an optional title argument. The following options are also supported:

`label`

: textA unique identifier for your algorithm that you can use to reference it with

`{prf:ref}`

. Cannot contain spaces or special characters.`class`

: textValue of the algorithm’s class attribute which can be used to add custom CSS or JavaScript.

`nonumber`

: flag (empty)Turns off algorithm auto numbering.

**Example**

(Ford–Fulkerson)

**Inputs** Given a Network \(G=(V,E)\) with flow capacity \(c\), a source node \(s\), and a sink node \(t\)

**Output** Compute a flow \(f\) from \(s\) to \(t\) of maximum value

\(f(u, v) \leftarrow 0\) for all edges \((u,v)\)

While there is a path \(p\) from \(s\) to \(t\) in \(G_{f}\) such that \(c_{f}(u,v)>0\) for all edges \((u,v) \in p\):

Find \(c_{f}(p)= \min \{c_{f}(u,v):(u,v)\in p\}\)

For each edge \((u,v) \in p\)

\(f(u,v) \leftarrow f(u,v) + c_{f}(p)\)

*(Send flow along the path)*\(f(u,v) \leftarrow f(u,v) - c_{f}(p)\)

*(The flow might be “returned” later)*

**MyST Syntax**

```
```{prf:algorithm} Ford–Fulkerson
:label: my-algorithm
**Inputs** Given a Network $G=(V,E)$ with flow capacity $c$, a source node $s$, and a sink node $t$
**Output** Compute a flow $f$ from $s$ to $t$ of maximum value
1. $f(u, v) \leftarrow 0$ for all edges $(u,v)$
2. While there is a path $p$ from $s$ to $t$ in $G_{f}$ such that $c_{f}(u,v)>0$
for all edges $(u,v) \in p$:
1. Find $c_{f}(p)= \min \{c_{f}(u,v):(u,v)\in p\}$
2. For each edge $(u,v) \in p$
1. $f(u,v) \leftarrow f(u,v) + c_{f}(p)$ *(Send flow along the path)*
2. $f(u,v) \leftarrow f(u,v) - c_{f}(p)$ *(The flow might be "returned" later)*
```
```

*Source:* Wikipedia

#### Referencing Algorithms¶

You can refer to a algorithms using the `{prf:ref}`

role like: `{prf:ref}`my-algorithm` `

, which will replace the reference with the algorithm number like so: Algorithm 1. When an explicit text is provided, this caption will serve as the title of the reference.

### Examples¶

An example directive can be included using the `prf:example`

pattern. The directive is enumerated by default and can take in an optional title argument. The following options are also supported:

`label`

: textA unique identifier for your example that you can use to reference it with

`{prf:ref}`

. Cannot contain spaces or special characters.`class`

: textValue of the example’s class attribute which can be used to add custom CSS or JavaScript.

`nonumber`

: flag (empty)Turns off example auto numbering.

**Example**

Next, we shut down randomness in demand and assume that the demand shock \(\nu_t\) follows a deterministic path:

Again, we’ll compute and display outcomes in some figures

```
ex2 = SmoothingExample(C2=[[0], [0]])
x0 = [0, 1, 0]
ex2.simulate(x0)
```

**MyST Syntax**

```
````{prf:example}
:label: my-example
Next, we shut down randomness in demand and assume that the demand shock
$\nu_t$ follows a deterministic path:
```{math}
\nu_t = \alpha + \rho \nu_{t-1}
```
Again, we’ll compute and display outcomes in some figures
```python
ex2 = SmoothingExample(C2=[[0], [0]])
x0 = [0, 1, 0]
ex2.simulate(x0)
```
````
```

*Source:* QuantEcon

### Properties¶

A property directive can be included using the `prf:property`

pattern. The directive is enumerated by default and can take in an optional title argument. The following options are also supported:

`label`

: textA unique identifier for your property that you can use to reference it with

`{prf:ref}`

. Cannot contain spaces or special characters.`class`

: textValue of the property’s class attribute which can be used to add custom CSS or JavaScript.

`nonumber`

: flag (empty)Turns off property auto numbering.

**Example**

This is a dummy property to illustrate the directive.

**MyST Syntax**

```
```{prf:property}
:label: my-property
This is a dummy property to illustrate the directive.
```
```

#### Referencing Properties¶

You can refer to a property using the `{prf:ref}`

role like: `{prf:ref}`my-property` `

, which will replace the reference with the property number like so: Property 1. When an explicit text is provided, this caption will serve as the title of the reference.

### Observations¶

An observation directive can be included using the `prf:observation`

pattern. The directive is enumerated by default and can take in an optional title argument. The following options are also supported:

`label`

: textA unique identifier for your observation that you can use to reference it with

`{prf:ref}`

. Cannot contain spaces or special characters.`class`

: textValue of the observation’s class attribute which can be used to add custom CSS or JavaScript.

`nonumber`

: flag (empty)Turns off observation auto numbering.

**Example**

This is a dummy observation directive.

**MyST Syntax**

```
```{prf:observation}
:label: my-observation
This is a dummy observation directive.
```
```

#### Referencing Observations¶

You can refer to an observation using the `{prf:ref}`

role like: `{prf:ref}`my-observation` `

, which will replace the reference with the observation number like so: Observation 1. When an explicit text is provided, this caption will serve as the title of the reference.

### Propositions¶

A proposition directive can be included using the `prf:proposition`

pattern. The directive is enumerated by default and can take in an optional title argument. The following options are also supported:

`label`

: textA unique identifier for your proposition that you can use to reference it with

`{prf:ref}`

. Cannot contain spaces or special characters.`class`

: textValue of the proposition’s class attribute which can be used to add custom CSS or JavaScript.

`nonumber`

: flag (empty)Turns off proposition auto numbering.

**Example**

This is a dummy proposition directive.

**MyST Syntax**

```
```{prf:proposition}
:label: my-proposition
This is a dummy proposition directive.
```
```

#### Referencing Propositions¶

You can refer to a proposition using the `{prf:ref}`

role like: `{prf:ref}`my-proposition` `

, which will replace the reference with the proposition number like so: Proposition 1. When an explicit text is provided, this caption will serve as the title of the reference.

## How to Hide Content¶

Directive content can be hidden using the `dropdown`

class which is available through sphinx-togglebutton. If your project utilizes the MyST-NB extension, there is no need to activate `sphinx-togglebutton`

since it is already bundled with `MyST-NB`

.

For Sphinx projects, add `"sphinx_togglebutton"`

to your `extensions`

list in `conf.py`

to activate the extension

```
extensions = [
...
"sphinx_togglebutton"
...
]
```

For Jupyter Book projects, add `sphinx_togglebutton`

under `extra_extensions`

```
sphinx:
extra_extensions:
- sphinx_togglebutton
```

To hide the directive, simply add `:class: dropdown`

as a directive option.

**Example**

This is an example of how to hide the content of a directive.

**MyST Syntax**:

```
```{prf:theorem}
:class: dropdown
This is an example of how to hide the content of a directive.
```
```