examples/creating-expressions.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "4db583af",
   "metadata": {},
   "source": [
    "# Creating Expressions\n",
    "\n",
    "In this notebook, we look at different options to create expressions. A strong focus will be set on the array-like operations: Since variables are represented in array-like structure, we benefit from a lot of well-knwon functionalities which we know from `numpy`, `pandas` or `xarray`.\n",
    "\n",
    "\n",
    "These are for example\n",
    "\n",
    "- `arithmetic` operations to create expressions\n",
    "- `broadcasting` to combine smaller and larger arrays\n",
    "- `.loc` to select a subset of the original array using indexes\n",
    "- `.where` to select where the variable or expression should be active or not\n",
    "- `.shift` to shift the whole array along one dimension\n",
    "- `.groupby` to group by a key and apply operations on the groups \n",
    "- `.rolling` to perform a rolling operation and perform operations\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "f3712718",
   "metadata": {},
   "source": [
    ".. hint::\n",
    "   Nearly all of the functions and properties, that can be accessed from a `Variable`, can be accesses from a `LinearExpression` and `QuadraticExpression`."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "95b25d13",
   "metadata": {},
   "source": [
    "Let's start by creating a model."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "close-maximum",
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "import xarray as xr\n",
    "\n",
    "import linopy\n",
    "\n",
    "time = pd.Index(range(10), name=\"time\")\n",
    "port = pd.Index(list(\"abcd\"), name=\"port\")\n",
    "\n",
    "m = linopy.Model()\n",
    "x = m.add_variables(lower=0, coords=[time], name=\"x\")\n",
    "y = m.add_variables(lower=0, coords=[time, port], name=\"y\")\n",
    "m"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "582a0cad",
   "metadata": {},
   "source": [
    "## Arithmetic Operations\n",
    "\n",
    "Arithmetic operations such as addition (`+`), subtraction (`-`), multiplication (`*`) can be used directly on the variables and expressions in Linopy. These operations are applied element-wise on the variables.\n",
    "\n",
    "For example, if you want to create a new combined expr `z` that is the sum of `x` and `y`, you can do so as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0aec195a",
   "metadata": {},
   "outputs": [],
   "source": [
    "z = x + y\n",
    "z"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "8c4b9ea6",
   "metadata": {},
   "source": [
    ".. note::\n",
    "   In the addition, the variable `x` is broadcasted and the return value has the same set of dimensions as `y`.  "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "a1de2b9a",
   "metadata": {},
   "source": [
    "Similarly, you can subtract `y` from `x` or multiply `x` and `y` as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c56761cd",
   "metadata": {},
   "outputs": [],
   "source": [
    "z = x - y\n",
    "z"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b59fa397",
   "metadata": {},
   "outputs": [],
   "source": [
    "z = x * y\n",
    "z"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "0ca00a73",
   "metadata": {},
   "source": [
    "In all cases, the returned shape is the same. Note that, the output type of the multiplication is a `QuadraticExpression` and not a `LinearExpression`.\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "3ff0d1cd",
   "metadata": {},
   "source": [
    "The `z` expression, which carries along `x` and `y`, has different attributes such as `coord_dims`, `dims`, `size`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "35c7331f",
   "metadata": {},
   "outputs": [],
   "source": [
    "z.coord_dims"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "f7578221",
   "metadata": {},
   "source": [
    ".. important::\n",
    "   When combining variables or expression with dimensions of the same name and size, the first object will determine the coordinates of the resulting expression. For example: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8c511f35",
   "metadata": {},
   "outputs": [],
   "source": [
    "other_time = pd.Index(range(10, 20), name=\"time\")\n",
    "b = m.add_variables(coords=[other_time], name=\"b\")\n",
    "b"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "59f43468",
   "metadata": {},
   "source": [
    "`b` has the same shape as `x`, but they have different coordinates. When we combine `x` and `b` the coordinates on dimension `time` will be taken from the first object and the coordinates of the subsequent object will be ignored:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "26edd6ab",
   "metadata": {},
   "outputs": [],
   "source": [
    "x + b"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "de6d3073",
   "metadata": {},
   "source": [
    "## Using `.loc` to select a subset\n",
    "\n",
    "The `.loc` function allows you to select a subset of the array using indexes. This is useful when you want to apply operations to a specific subset of your variables.\n",
    "\n",
    "For example, if you want to apply a summation to the variables `x` and `y` only for the first 5 time steps, you can do so as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "93119cfc",
   "metadata": {},
   "outputs": [],
   "source": [
    "x.loc[:5]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ae6a1b29",
   "metadata": {},
   "outputs": [],
   "source": [
    "x.loc[:5] + y.loc[:5]"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "14b02f7d",
   "metadata": {},
   "source": [
    "which is the same as"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7281f08c",
   "metadata": {},
   "outputs": [],
   "source": [
    "expr = x + y\n",
    "expr.loc[:5]"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "c3c97abf",
   "metadata": {},
   "source": [
    "In combination with the overwrite of the coordinates, this is useful when you need to combine different selections, like"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "27063ea9",
   "metadata": {},
   "outputs": [],
   "source": [
    "x.loc[:4] + y.loc[5:]"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "cdb53f49",
   "metadata": {},
   "source": [
    "## Using `.where` to select active variables or expressions\n",
    "\n",
    "The `.where` function allows you to select where the variable or expression should be active or not. This is useful when you want to apply constraints or operations only to a specific subset of your variables based on a condition. It is quite similar to the functionality of masking, that we showed earlier.\n",
    "\n",
    "For example, if you want to create an sum of the variables `x` and `y` where `time` is greater than 2, you can do so as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ab8f59fd",
   "metadata": {},
   "outputs": [],
   "source": [
    "mask = xr.DataArray(time > 2, coords=[time])\n",
    "(x + y).where(mask)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "3ee10a58",
   "metadata": {},
   "source": [
    "We can use this to make a conditional summation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "21fa9664",
   "metadata": {},
   "outputs": [],
   "source": [
    "(x + y).where(mask) + xr.DataArray(5, coords=[time]).where(~mask, 0)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "652973ea",
   "metadata": {},
   "source": [
    "## Using `.shift` to shift the Variable along one dimension\n",
    "\n",
    "The `.shift` function allows you to shift the whole array along one dimension. This is useful when you want to apply constraints or operations that involve a time delay or a shift in the time steps.\n",
    "\n",
    "For example, if you want to apply a constraint that involves a one time step delay in the variables `x` and `y`, you can do so as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "organized-hampshire",
   "metadata": {},
   "outputs": [],
   "source": [
    "y - y.shift(time=1)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "eaf3f38c",
   "metadata": {},
   "source": [
    "## Using `.groupby` to group by a key and apply operations on the groups\n",
    "\n",
    "The `.groupby` function allows you to group by a key and apply operations on the groups. This is useful when you want to apply constraints or operations that involve a grouping of the time steps or any other dimension.\n",
    "\n",
    "For example, if you want to apply a constraint that involves the sum of `x` and `y` over every two time steps, you can do so as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5170d187",
   "metadata": {},
   "outputs": [],
   "source": [
    "group_key = pd.Series(time.values // 2, index=time)\n",
    "(x + y).groupby(group_key).sum()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "7ded9a54",
   "metadata": {},
   "source": [
    "## Using `.rolling` to perform a rolling operation\n",
    "\n",
    "The `.rolling` function allows you to perform a rolling operation and apply operations. This is useful when you want to apply constraints or operations that involve a rolling window of the time steps or any other dimension.\n",
    "\n",
    "For example, if you want to apply a constraint that involves the sum of `x` over a rolling window of 3 time steps, you can do so as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d703fb70",
   "metadata": {},
   "outputs": [],
   "source": [
    "x.rolling(time=3).sum()"
   ]
  }
 ],
 "metadata": {
  "@webio": {
   "lastCommId": null,
   "lastKernelId": null
  },
  "kernelspec": {
   "display_name": "Python 3",
   "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.11.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}