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.
```