"Gennaker is an app that lets you read or write a type of document called a booklet. The characteristic feature of a booklet is that it can conveys ideas that are codified in three complementary ways:\n",
"\n",
"- natural language \n",
"- mathematics\n",
"- computer code"
]
},
{
"cell_type": "markdown",
"id": "517e5455-1e48-4c31-82b9-10e784e0df1d",
"metadata": {},
"source": [
"## Python and Notebooks\n",
"\n",
"Python is the default code dialect because it is programming language that is closest to a universal second language. \n",
"\n",
"Gennaker relies heavily on JupyterLab (henceforth JL) and its notebooks. A JL notebook is essentially a text file with code like any other but better comments. \n",
"\n",
"Neither Gennaker nor JupyterLab try to be an integrated developoment environment (IDE) for writing code. JupyterLab is a toolkit. Gennaker is a collection of tools that make it easy for authors can use to create and distribute technical documents and equally easy for readers to read and experiment with such documents. "
]
},
{
"cell_type": "markdown",
"id": "91372beb-4cd8-40ef-bd17-2541eb46ca2c",
"metadata": {},
"source": [
"## The Role for Gennaker\n",
"\n",
"In contrast to the familiar tools for creating and read PDFs, Gennaker is committed to equal treatment for authors and readers. \n",
"\n",
"It is also intended as a set of “training wheels” that make it easy for someone to started using Python and JupyterLab to read and write documents that are like PDFs with working code. Like JupyterLab, Gennaker is open source. The people who are developing Gennaker have zero incentive to lock you into using it. Like training wheels for bicycles, Gennaker succeeds when people stop using it. \n",
"\n",
"If you are working on macOS or Windows and aren't familiar with Python and JupyterLab, Gennaker makes it trivial to get up and running. All you have to do is download and install an app. (If you are working on Linux, you don't need training wheels.) "
]
},
{
"cell_type": "markdown",
"id": "e2f4a448-ea61-4fa3-90b3-2721869da6be",
"metadata": {},
"source": [
"## Booklets\n",
"Gennaker is organizes its documents as booklets. In many ways, a booklet is like a software project that will eventually be published as a library. Booklets should also be published, and might even be published on sites such as [`http://pypi.org`](https://pypi.org) that distributes code libraries, but a more natural channel might be a reasearch paper repository analogous to [`https://arxiv.org`](https://arxiv.org) or [`https://nber.org`](https://nber.org). \n",
"\n",
"Booklets will often (but not always) include a JupyterLab notebook. Frequently they will include other files too. If you look in the browser bar to the right, you'll see that this booklet includes both this notebook, with the characteristic suffix, `.ipynb` and a comma-separated-value file `data.csv` that the code in the notebook reads from.\n"
]
},
{
"cell_type": "markdown",
"id": "a2db5ad7-c267-481b-ba5d-7fc4d233dc87",
"metadata": {},
"source": [
"## Clean and Classic Notebook Interfaces\n",
"When you open a notebook that was authored inside Gennaker, the default is to display a decluttered version of the classic user interface of JupyterLab. The file format for a notebook is unchanged, so there are many possibilities: \n",
"\n",
"- An author can publish a booklet with notebooks that by default using either the clean interface or JupyterLab's classic, full-featured interface.\n",
"\n",
"- No matter what the author decided, a reader can choose which interface to use to display a notebook. \n",
"\n",
"If you want to see a side by side comparision of the two interfaces, use the main Gennaker page to open the “Classic JupyterLab” booklet. It has a copy of this notebook. Open it and compare it to this version of the notebook to see the difference in the interfaces. "
]
},
{
"cell_type": "markdown",
"id": "3fb874ca-68d9-42e8-ba21-27baf45ab194",
"metadata": {},
"source": [
"## What You Can Do With a Gennaker Booklet"
]
},
{
"cell_type": "markdown",
"id": "21550cd0-10ab-40d9-9fba-b857c68dae09",
"metadata": {},
"source": [
"### Latex Math and Symbolic Calculations"
]
},
{
"cell_type": "markdown",
"id": "7372ef42-1920-4467-b9d9-e2c6b7125705",
"metadata": {},
"source": [
"You can display typeset mathematics using markup from Latex that you type in by hand:\n",
"$$V = \\sum_{t = 0}^{\\infty} \\beta^t x_t$$\n"
]
},
{
"cell_type": "markdown",
"id": "4565cef2-2b60-447d-995e-b3c478835bbc",
"metadata": {},
"source": [
"You sometimes it is easier to build up complex Latex expressions by composing functions. For example, to specify a time dependent desity function you can define some functions and compose them:"
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "afc66e23-7f0c-40bf-9149-6a0fb1f37c75",
"metadata": {},
"outputs": [
{
"data": {
"text/latex": [
"$\\displaystyle \\left( x \\mapsto e^{- \\frac{1}{x^{2}}} \\right)$"
"The Python workhorses for scientific visualization and data analysis have long been `matplotlib` and `pandas`. The default package manager was `pip`.\n",
"\n",
"These are widely used and well tested, so of course, Gennaker supports them. But there are newer possibilities you can try. \n",
"\n",
"The `uv` library can speed things up dramatically, especially on Windows. If you are familiar with `ggplot` from `R`. you might want to try the `plotnine` library. Here, we'll use `polars` to turn a `csv` file into the type of dataframe that `ggplot` expects. \n",
"\n",
"If we wanted to hide these details from the reader, we could put some of what follows into a `.py` and import from it, just as we did for SymPy. Instead, we can do the `uv` version of a `pip install` on the fly by using the `!` operator to have JupyterLab pass a command onto the operating system shell instead of giving it to the Python interpreter:"
"We can define a Python dictionary `dtypes` to override the default assumptions that Polars would otherwise make when it reads the data from the `csv` file. "
