Add the transport tutorial

.github/workflows/pytest.yaml

@@ -194,7 +194,7 @@ jobs:
       #------------------------------------------------
       - name: Install dependencies
         if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
-        run: poetry install --no-interaction --no-root --with dev,server
+        run: poetry install --no-interaction --no-root --with dev,server,tutorial
 
       #------------------------
       #  install root project

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
 - repo: https://github.com/pre-commit/mirrors-mypy
-  rev: v1.13.0
+  rev: v1.14.1
   hooks:
   - id: mypy
     entry: bash -c "poetry run mypy ."

pyproject.toml

@@ -72,7 +72,9 @@ types-toml = ">=0.10.8.7"
 optional = true
 
 [tool.poetry.group.tutorial.dependencies]
+highspy = ">=1.7.2"
 ipykernel = ">=6.27.1"
+linopy = ">=0.3.10"
 
 [tool.poetry.scripts]
 ixmp4 = "ixmp4.__main__:app"

tutorial/transport/0_transport-tutorial_platform-setup.ipynb

@@ -0,0 +1,221 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "9398de15-4422-46d5-815f-99bf4ef36673",
+   "metadata": {},
+   "source": [
+    "### Transport Tutorial - Notebook 0 \n",
+    "\n",
+    "# Set up an **ixmp4** platform to solve *Dantzig's Transport Problem*\n",
+    "\n",
+    "## Aim and scope of this tutorial\n",
+    "\n",
+    "This tutorial takes you through the steps to solve a simple optimization model\n",
+    "using the **ixmp4** database management package and the **linopy** optimization package.\n",
+    "\n",
+    "We use **Dantzig's transport problem**, which is used as a [tutorial for linopy](https://linopy.readthedocs.io/en/latest/transport-tutorial.html).\n",
+    "This problem solves for a least-cost shipping schedule that meets demand constraints at several markets (cities)\n",
+    "and supply constraints at factories.\n",
+    "\n",
+    "For reference of the transport problem, see:\n",
+    "> Dantzig, G B, Chapter 3.3. In Linear Programming and Extensions.  \n",
+    "> Princeton University Press, Princeton, New Jersey, 1963.\n",
+    "\n",
+    "## Tutorial outline\n",
+    "\n",
+    "This tutorial consists of three Jupyter notebooks:\n",
+    "\n",
+    "0. Set up an `ixmp4.Platform` to store the scenario input data and solution\n",
+    "1. Implement the **baseline version of the transport problem** and solve it\n",
+    "2. Create an **alternative scenario** and solve it "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6f4eb5bd-095c-4342-b02b-666cef908c6d",
+   "metadata": {},
+   "source": [
+    "## Setting up the database instance via the Command Line Interface (CLI)\n",
+    "\n",
+    "An [**ixmp4.Platform**](https://docs.ece.iiasa.ac.at/projects/ixmp4/en/latest/devs/ixmp4.core/platform.html#ixmp4.core.platform.Platform)\n",
+    "is the connection to a database instance that can hold scenario data and relevant additional information.\n",
+    "\n",
+    "<div class=\"alert alert-warning\">\n",
+    "\n",
+    "You only need to run this notebook when you work through the transport tutorial for the first time </br>\n",
+    "(or when you decided to delete the local database)!\n",
+    "\n",
+    "</div>\n",
+    "\n",
+    "Run the following in the command-line to create a new SQLite database instance called `transport-tutorial`:\n",
+    "```\n",
+    "ixmp4 platforms add transport-tutorial\n",
+    "```\n",
+    "The prompt will ask whether you really want to create a local database instance, answer `yes` or `y`.\n",
+    "\n",
+    "\n",
+    "You can then check if the database was successfully created by running:\n",
+    "```\n",
+    "ixmp4 platforms list\n",
+    "```\n",
+    "\n",
+    "The log output will show the locally available databases (on your computer) as well as  \n",
+    "the **ixmp4** databases hosted by the [IIASA Scenario Services](https://docs.ece.iiasa.ac.at) team.\n",
+    "\n",
+    "After creating the database, you can connect to it via an **ixmp4.Platform** instance."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5c93c843-e30d-45fd-b01d-f2d3213d9f30",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import ixmp4\n",
+    "\n",
+    "platform = ixmp4.Platform(\"transport-tutorial\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b6209e20-9979-4f3b-b6b7-fe37a1c09366",
+   "metadata": {},
+   "source": [
+    "## Defining units in the `Platform` and database\n",
+    "\n",
+    "The **ixmp4** package requires that units are defined explicitly before adding data using them.\n",
+    "\n",
+    "The transport tutorial uses the units \"cases\", \"1000 miles\" and \"dollars per case per 1000 miles\"."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "9be63ed0-aca6-44e3-a6c6-d8fdf8ec2549",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "for unit in [\"cases\", \"1000 miles\", \"dollars per case per 1000 miles\"]:\n",
+    "    platform.units.create(unit)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "85c380fb-b29c-4f26-b70d-9d3cdaa42a99",
+   "metadata": {},
+   "source": [
+    "You can get a list of all `Unit`s defined in the **ixmp4.Platform** using the `tabulate()` method."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "98f37ba9-7218-428e-953a-107534cbfc12",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "platform.units.tabulate()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5b67ad18-13d3-40b4-9502-f926e753cf07",
+   "metadata": {},
+   "source": [
+    "<div class=\"alert alert-warning\">\n",
+    "\n",
+    "Defining an **ixmp4.Unit** again (i.e., creating one that is already defined in the database) will raise an error!\n",
+    "\n",
+    "</div>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1e7f631c-67d5-4170-858d-c96636c5e765",
+   "metadata": {},
+   "source": [
+    "One reason for defining units explicitly is so that we can assign docstrings to them.\n",
+    "\n",
+    "First, we get a specific **ixmp4.Unit** from the platform. Then, we add a docstring. Third, we illustrate how to retrieve the docstring. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "500b36df-c528-4109-bc62-ab326af34f5e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "cases = platform.units.get(\"cases\")\n",
+    "cases"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "6c1a395d-6c8a-489c-9aa8-39d24895ca51",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "cases.docs = \"Unit of a good produced at canning plants and consumed at markets\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ca1ccd87-03ac-4c29-bd45-0f253a7826c4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "cases.docs"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9bae066c-07c4-4550-8b40-5db2fb9a7049",
+   "metadata": {},
+   "source": [
+    "## Cleaning up after doing this tutorial\n",
+    "\n",
+    "You can use the **ixmp4** Command Line Interface (CLI) to remove the database related to this tutorial.\n",
+    "\n",
+    "<div class=\"alert alert-warning\">\n",
+    "\n",
+    "You still need this database in order to run Notebook 1 and Notebook 2, so don't do this right away!\n",
+    "\n",
+    "</div>\n",
+    "\n",
+    "Run the following in the command-line:\n",
+    "```\n",
+    "ixmp4 platforms remove transport-tutorial\n",
+    "```\n",
+    "\n",
+    "The prompt will ask whether you also want to delete the SQLite database file from your computer, \n",
+    "answer `y` for a complete deletion."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}