---
jupytext:
text_representation:
extension: .md
format_name: myst
kernelspec:
display_name: Python 3
language: python
name: python3
---
# Exercises and Proofs
There are two extensions for jupyterbook that enable us to add
[exercises](https://ebp-sphinx-exercise.readthedocs.io/en/latest/)
and [proofs](https://sphinx-proof.readthedocs.io/en/latest/) in our lecture series.
These extensions provide a beautiful and clear separation from the text and offer a better reading experience.
## Exercises
```{seealso}
To learn more about [sphinx-exercise](https://ebp-sphinx-exercise.readthedocs.io/en/latest/)
please read the [documentation](https://ebp-sphinx-exercise.readthedocs.io/en/latest/).
```
Here we provide a brief tutorial on using `exercise` admonitions in the `quantecon` lectures
To make an exercise you can use the `exercise` admonition
````md
```{exercise}
:label: my-exercise
Recall that $n!$ is read as "$n$ factorial" and defined as
$n! = n \times (n - 1) \times \cdots \times 2 \times 1$.
There are functions to compute this in various modules, but let's
write our own version as an exercise.
In particular, write a function `factorial` such that `factorial(n)` returns $n!$
for any positive integer $n$.
```
````
where the `label` enables you to reference the exercise using `ref` or `numref` roles.
This will be rendered as
```{exercise}
:label: my-exercise
Recall that $n!$ is read as "$n$ factorial" and defined as
$n! = n \times (n - 1) \times \cdots \times 2 \times 1$.
There are functions to compute this in various modules, but let's
write our own version as an exercise.
In particular, write a function `factorial` such that `factorial(n)` returns $n!$
for any positive integer $n$.
```
and then you can easily reference the exercise using the `{ref}` role ({ref}`my-exercise`) or using the `{numref}` role ({numref}`my-exercise`).
```{seealso}
There are [additional configuration options available](https://ebp-sphinx-exercise.readthedocs.io/en/latest/syntax.html#exercise-directive)
but are not frequently used in `QuantEcon` lectures
```
Each exercise admonition should be paired with a `solution` admonition.
The exercise extension also provides us with a useful property that enables us to convert our solutions into a dropdown paragraph.
This helps the reader to have more time to think about the questions without being tempted by the solution.
You can add this feature in `class`.
```{admonition} Guiding Principle
* Use [gated syntax](https://ebp-sphinx-exercise.readthedocs.io/en/latest/syntax.html#alternative-gated-syntax) whenever your exercise uses:
* executable code cells
* any nested directives (such as `math`, `note` etc.)
* Use `:class: dropdown` for solutions by default
```
````md
```{solution-start} my-exercise
:class: dropdown
:label: my-solution
```
Here's one solution.
```{code-cell} python
def factorial(n):
k = 1
for i in range(n):
k = k * (i + 1)
return k
factorial(4)
```
```{solution-end}
```
````
which is rendered as
```{solution-start} my-exercise
:class: dropdown
:label: my-solution
```
Here's one solution.
```{code-cell} python
def factorial(n):
k = 1
for i in range(n):
k = k * (i + 1)
return k
factorial(4)
```
```{solution-end}
```
The `solution` can be `referenced` using the `label` property using `ref` and `numref`.
The `solution` directive **requires** the label of the exercise.
Given many solutions across QuantEcon projects typically require code execution we frequently make use of the `gated syntax`.
**Note:** If a solution does **not require code execution** it is possible to use the primary `solution` admonition.
```{warning}
The code in this example is **not** executed but **is** syntax highlighted
```
`````md
````{solution} my-exercise
:label: my-solution
Here's one solution.
```{code-block} python
def factorial(n):
k = 1
for i in range(n):
k = k * (i + 1)
return k
factorial(4)
```
````
`````
which is rendered as
````{solution} my-exercise
:label: my-solution2
Here's one solution.
```{code-block} python
def factorial(n):
k = 1
for i in range(n):
k = k * (i + 1)
return k
factorial(4)
```
````
## Proofs
There is a range of directives provided by [sphinx-proof](https://sphinx-proof.readthedocs.io/en/latest/):
1. [prf:proof](https://sphinx-proof.readthedocs.io/en/latest/syntax.html#proofs)
2. [prf:theorem](https://sphinx-proof.readthedocs.io/en/latest/syntax.html#theorems)
3. [prf:axiom](https://sphinx-proof.readthedocs.io/en/latest/syntax.html#axioms)
4. [prf:lemma](https://sphinx-proof.readthedocs.io/en/latest/syntax.html#lemmas)
5. [prf:definition](https://sphinx-proof.readthedocs.io/en/latest/syntax.html#definitions)
6. [prf:criteria](https://sphinx-proof.readthedocs.io/en/latest/syntax.html#criteria)
7. [prf:remark](https://sphinx-proof.readthedocs.io/en/latest/syntax.html#remarks)
8. [prf:conjecture](https://sphinx-proof.readthedocs.io/en/latest/syntax.html#conjectures)
9. [prf:corollary](https://sphinx-proof.readthedocs.io/en/latest/syntax.html#corollaries)
10. [prf:algorithm](https://sphinx-proof.readthedocs.io/en/latest/syntax.html#algorithms)
11. [prf:example](https://sphinx-proof.readthedocs.io/en/latest/syntax.html#examples)
12. [prf:property](https://sphinx-proof.readthedocs.io/en/latest/syntax.html#properties)
13. [prf:observation](https://sphinx-proof.readthedocs.io/en/latest/syntax.html#observations)
14. [prf:proposition](https://sphinx-proof.readthedocs.io/en/latest/syntax.html#propositions)
15. [prf:assumption](https://sphinx-proof.readthedocs.io/en/latest/syntax.html#assumptions)
```{note}
The `prf:` included in each directive name **is required** in both the `directive` and when
referencing the admonition such as `{prf:ref}`. These belong to the Sphinx `prf` domain that supports
references and linking.
```
An example proof:
```{tip}
This package does **not** support the `gated syntax` provided by `sphinx-exercise`, therefore
you need to use `nested` ticks if including other directives such as `math` as is shown in this example.
```
`````
````{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.
```
````
`````
will render as
````{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.
````