Add xeus-cpp tutorial notebooks

xeus-cpp/01_verification.ipynb

@@ -0,0 +1,57 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "333cda22-5985-44ed-9bcc-5f34378c1bec",
+   "metadata": {},
+   "source": [
+    "# Environment setup and basic verification\n",
+    "\n",
+    "---"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "884a03ad-230a-4725-90fd-939990e123da",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "C++ Version: 202302\n",
+      "42\n"
+     ]
+    }
+   ],
+   "source": [
+    "#include <iostream>\n",
+    "\n",
+    "std::cout << \"C++ Version: \" << __cplusplus << std::endl; //Checks C++ version\n",
+    "\n",
+    "int a = 10;\n",
+    "int b = 32;\n",
+    "std::cout << a + b << std::endl;\n",
+    "//Conducts a basic mathematical operation\n",
+    "//Checks kernel responsiveness"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "C++23",
+   "language": "cpp",
+   "name": "xcpp23"
+  },
+  "language_info": {
+   "codemirror_mode": "text/x-c++src",
+   "file_extension": ".cpp",
+   "mimetype": "text/x-c++src",
+   "name": "C++",
+   "version": "23"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

xeus-cpp/02_persistence.ipynb

@@ -0,0 +1,113 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "bbff0978-540f-4307-96fb-6a4692e4fd4d",
+   "metadata": {},
+   "source": [
+    "# State persistence across cells in xeus-cpp\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "35740592-c29e-4c7b-87e8-52cc0060cd59",
+   "metadata": {},
+   "source": [
+    "#### In a standard C++ development invironment, each time you run a program, the memory is allocated, the `main()` function executes, and then the memory is completely wiped. In **xeus-cpp**, the execution model is **persistent**\n",
+    "\n",
+    "---"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ed28c993-b195-4eb1-85cc-fee63cb04470",
+   "metadata": {},
+   "source": [
+    "\n",
+    "### What is state persistence?\n",
+    "\n",
+    "The Jupyter notebook acts as a single, ongoing C++ session. When you execute a cell, the kernel compiles that specific snippet and integrates it into the current process memory. This means, that any variable, function or object defined in a cell remains alive and accessible in any other cell.\n",
+    "\n",
+    "***NB! The order in which you run cells matters. Running cells out of order can cause errors and unexpected behaviour***"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b493b694-04f1-4a01-997f-ceb4ef8d1499",
+   "metadata": {},
+   "source": [
+    "\n",
+    "### The following program demonstrates how state persistence in xeus-cpp works exactly:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "b2d303a7-96ee-4aeb-8c84-4884bba161f6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "int counter = 0;"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "d541cb78-b2ae-4175-b9ae-a76014a37e28",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#include <iostream>\n",
+    "\n",
+    "void inc()\n",
+    "{\n",
+    "    counter++;\n",
+    "    std::cout << \"Current Value: \" << counter << std::endl;\n",
+    "}"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "d2c38c70-3e92-446a-8c10-1c62edf177e1",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Current Value: 2\n"
+     ]
+    }
+   ],
+   "source": [
+    "inc(); //Run this cell multiple times to see persistence in action"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e4068173-ab1b-44e5-b439-a4063adfaa67",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "C++23",
+   "language": "cpp",
+   "name": "xcpp23"
+  },
+  "language_info": {
+   "codemirror_mode": "text/x-c++src",
+   "file_extension": ".cpp",
+   "mimetype": "text/x-c++src",
+   "name": "C++",
+   "version": "23"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

xeus-cpp/03_redefinition.ipynb

@@ -0,0 +1,168 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "d7a1b687-3743-4786-84b0-71b6eed7d62e",
+   "metadata": {},
+   "source": [
+    "# Testing redefinition behaviour\n",
+    "\n",
+    "\n",
+    "#### In a traditional C++ workflow, you write code in a `.cpp` file, compile it all at once, and run it. If you want to change a variable type, you simply edit the file and recompile. However, **xeus-cpp**'s cell-based workflow enables several workarounds\n",
+    "---"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "96f3d068-6433-472a-a4b7-02f253a22600",
+   "metadata": {},
+   "source": [
+    "In this example, we declare a variable with an `int` type, which we will name `a`, and assign a value to it"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "216e746c-4eae-4655-a18d-8e1fb6da4327",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Initial declaration: 100\n"
+     ]
+    }
+   ],
+   "source": [
+    "#include <iostream>\n",
+    "\n",
+    "int a = 100;\n",
+    "std::cout << \"Initial declaration: \" << a << std::endl;"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "991adb4c-e105-4f58-8b5d-1147c2ac8d6d",
+   "metadata": {},
+   "source": [
+    "Next, we try to redeclare the variable, this time to `double`, and assign a new value to it"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "54d35e14-c256-4692-8a7c-f5b7e3815030",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "double a = 55.5;\n",
+    "std::cout << \"New declaration: \" << a << std::endl;"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "df0fdee0-4747-4ba9-b242-76d8c870cdc5",
+   "metadata": {},
+   "source": [
+    "This action of redefinition is **illegal** in standard C++, because the variable `a` already exists as an `int`.\n",
+    "\n",
+    "Two workarounds exist:\n",
+    "- overwriting the value **without redeclaring the type**\n",
+    "- creating a temporary \"bubble\" by redeclaring it in a **different scope**, so the variables don't interfere. This method doesn't change the value or the type of the global variable\n",
+    "  \n",
+    "***NB!*** It is advised that unless you absolutely must use the same name for a variable, you simply pick a new name"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f52dad1c-3374-438b-9e6f-50e19470a057",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "\n",
+    "### First method - overwriting the value"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "0a466dd1-9301-4bd0-a981-491c7906ba8f",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Updated value: 20\n"
+     ]
+    }
+   ],
+   "source": [
+    "a = 20.8;\n",
+    "std::cout << \"Updated value: \" << a << std::endl;"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "90a1c883-bb3a-402f-bb12-d6aaa4f886db",
+   "metadata": {},
+   "source": [
+    "When using the first method to assign a floating point value to an `int`, the new value is floored to the closest integer\n",
+    "\n",
+    "As shown in this example \n",
+    "\n",
+    "> 20.8 --> 20"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "87b8d709-e706-4edd-888a-6d0a6a788b8a",
+   "metadata": {},
+   "source": [
+    "### Second method - redeclaring in a different scope"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "id": "0c765722-7a41-4b25-92df-c10dea32f5e3",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Updated value (scoped): 12.34\n",
+      "Global value: 20\n"
+     ]
+    }
+   ],
+   "source": [
+    "{\n",
+    "    float a = 12.34f; //safe because it's inside a local scope\n",
+    "    std::cout << \"Updated value (scoped): \" << a << std::endl;\n",
+    "}\n",
+    "\n",
+    "//Outside the brackets, the original int still exists\n",
+    "std::cout << \"Global value: \" << a << std::endl;"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "C++23",
+   "language": "cpp",
+   "name": "xcpp23"
+  },
+  "language_info": {
+   "codemirror_mode": "text/x-c++src",
+   "file_extension": ".cpp",
+   "mimetype": "text/x-c++src",
+   "name": "C++",
+   "version": "23"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}