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 : text

    Value 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

\[\| 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.

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 : text

    A unique identifier for your theorem that you can use to reference it with {prf:ref}. Cannot contain spaces or special characters.

  • class : text

    Value 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

Theorem 1 (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

\[\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\).

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 : text

    A unique identifier for your axiom that you can use to reference it with {prf:ref}. Cannot contain spaces or special characters.

  • class : text

    Value 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

Axiom 1 (Completeness of \(\mathbb{R}\))

Every 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]

Referencing Axioms

You can refer to an axiom using the {prf:ref} role like: {prf:ref}`my-axiom` , which will replace the reference with the axiom number like so: Axiom 1. When an explicit text is provided, this caption will serve as the title of the reference.

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 : text

    A unique identifier for your lemma that you can use to reference it with {prf:ref}. Cannot contain spaces or special characters.

  • class : text

    Value 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

Lemma 1

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), then

(1)\[K(\hat F, \theta) = (\theta I - C'\hat P C)^{-1} C' \hat P (A - B \hat F)\]

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

Referencing Lemmas

You can refer to a lemma using the {prf:ref} role like: {prf:ref}`my-lemma` , which will replace the reference with the lemma number like so: Lemma 1. When an explicit text is provided, this caption will serve as the title of the reference.

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 : text

    A unique identifier for your definition that you can use to reference it with {prf:ref}. Cannot contain spaces or special characters.

  • class : text

    Value 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

Definition 1

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

\[\begin{split} &\min_{\beta} \hspace{2mm} \beta \\ &\text{s.t. }\hspace{2mm}Bp \leq \beta Ap \end{split}\]

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 : text

    A unique identifier for your criterion that you can use to reference it with {prf:ref}. Cannot contain spaces or special characters.

  • class : text

    Value 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

Criterion 1 (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\),

\[\lim_{n \rightarrow \infty} \frac{1}{n} \sum_{j=1}^{n} \exp^{2 \pi i m a_j} = 0\]

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 : text

    A unique identifier for your remark that you can use to reference it with {prf:ref}. Cannot contain spaces or special characters.

  • class : text

    Value 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

Remark 1

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))

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

Referencing Remarks

You can refer to a remark using the {prf:ref} role like: {prf:ref}`my-remark` , which will replace the reference with the remark number like so: Remark 1. When an explicit text is provided, this caption will serve as the title of the reference.

Conjectures

Example

Conjecture 1 (Fake \(\gamma\) conjecture)

This 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 : text

    A unique identifier for your corollary that you can use to reference it with {prf:ref}. Cannot contain spaces or special characters.

  • class : text

    Value 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

Corollary 1

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 : text

    A unique identifier for your algorithm that you can use to reference it with {prf:ref}. Cannot contain spaces or special characters.

  • class : text

    Value 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

Algorithm 1 (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

  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)

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 : text

    A unique identifier for your example that you can use to reference it with {prf:ref}. Cannot contain spaces or special characters.

  • class : text

    Value 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

Example 1

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

\[\nu_t = \alpha + \rho \nu_{t-1}\]

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

Referencing Examples

You can refer to an example using the {prf:ref} role like: {prf:ref}`my-example` , which will replace the reference with the example number like so: Example 1. When an explicit text is provided, this caption will serve as the title of the reference.

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 : text

    A unique identifier for your property that you can use to reference it with {prf:ref}. Cannot contain spaces or special characters.

  • class : text

    Value 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

Property 1

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 : text

    A unique identifier for your observation that you can use to reference it with {prf:ref}. Cannot contain spaces or special characters.

  • class : text

    Value 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

Observation 1

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 : text

    A unique identifier for your proposition that you can use to reference it with {prf:ref}. Cannot contain spaces or special characters.

  • class : text

    Value 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

Proposition 1

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

MyST Syntax:

```{prf:theorem}
:class: dropdown

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