{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "dc0eaceb",
   "metadata": {},
   "source": [
    "# `GenericSeries` Tutorial\n",
    "\n",
    "## Introduction\n",
    "\n",
    "The `GenericSeries` class describes a potentially multi-dimensional quantity that depends on one or more dimensions.\n",
    "Some examples are the position of the welding torch that depends on time, or the workpiece temperature field that depends on time and space.\n",
    "The data of the `GenericSeries` can either be stored in form of explicit values or as a mathematical expression.\n",
    "It's main feature is that you can evaluate the data at any given coordinate of the dimensions it depends on.\n",
    "This happens either through interpolation if the data is discrete or through direct evaluation of the mathematical expression.\n",
    "We can use the `GenericSeries` in our scripts and jupyter notebooks by importing it from the WelDX python package:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a53fb427",
   "metadata": {},
   "outputs": [],
   "source": [
    "from weldx import GenericSeries  # isort: off"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d8389049",
   "metadata": {},
   "source": [
    "For this tutorial, we will also need to import the following packages and classes:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e4ab6db2",
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "import numpy as np\n",
    "from pint import DimensionalityError\n",
    "from xarray import DataArray\n",
    "\n",
    "from weldx import Q_"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "865b19c3",
   "metadata": {},
   "source": [
    "## Terminology\n",
    "\n",
    "Before we can start with the actual tutorial, we need to discuss some terminology.\n",
    "It is essential to understand the differences between the following terms to avoid confusion throughout the course of this tutorial.\n",
    "\n",
    "**Dimension**\n",
    "\n",
    "Each dimension describes a single degree of freedom. \n",
    "We can think of it as a 1d-coordinate axis. \n",
    "Using multiple dimensions will create a multi-dimensional space. \n",
    "A typical example would be the dimensions $x$, $y$, and $z$ that form 3d-space. \n",
    "Another popular dimension is time.\n",
    "\n",
    "**Coordinates**\n",
    "\n",
    "A coordinate is a specific value or label on the 1d-axis of a dimension. \n",
    "We can specify the location of a point in 3d-space by providing its coordinates. \n",
    "For example, we can use $x=1m$, $y=3m$, and $z=0m$.\n",
    "These are coordinates for the dimensions $x$, $y$, and $z$.\n",
    "Dimensions represent degrees of freedom, coordinates are discrete values of a dimension.\n",
    "\n",
    "**Variable**\n",
    "\n",
    "If a mathematical expression is used to describe the `GenericSeries`, the individual terms of this expression can be divided into two groups. \n",
    "The first group are variables. \n",
    "Variables are symbols that don't get values assigned to them during the creation of a `GenericSeries`.\n",
    "They let us evaluate the expression for different coordinates.\n",
    "Consider the following expression:\n",
    "\n",
    "$$\n",
    "2 \\cdot x + 3\n",
    "$$\n",
    "\n",
    "Here, $x$ is our variable. \n",
    "We can evaluate this expression over and over again by providing different values/coordinates for $x$.\n",
    "For example, if we would use $x=2$, the result is $7$. \n",
    "With $x=4$ we would get $11$. \n",
    "An important fact to note is that each variable of a `GenericSeries`' expression is a dimension. \n",
    "But not every dimension of an expression is necessarily represented by a variable.\n",
    "We will show some code examples later that make this more understandable.\n",
    "\n",
    "**Parameter**\n",
    "\n",
    "The second group of therms in an expression based `GenericSeries` are parameters.\n",
    "Parameters are also symbols of an expression, but in contrast to variables, they already get discrete values assigned to them.\n",
    "Consider the following expression:\n",
    "\n",
    "$$\n",
    "a \\cdot t + b\n",
    "$$\n",
    "\n",
    "with:\n",
    "\n",
    "$$\n",
    "\\begin{matrix}\n",
    "a=&3m/s\\\\\n",
    "b=&5m\n",
    "\\end{matrix}\n",
    "$$\n",
    "\n",
    "$a$ and $b$ are parameters, because they have values assigned to them. \n",
    "`t` is still a variable\n",
    "\n",
    "**Free dimension**\n",
    "\n",
    "Dimensions in an expression can either be represented by a variable or a parameter.\n",
    "To distinguish between both, we will refer to dimensions that are expression variables as \"free dimensions\"."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3fa2be44",
   "metadata": {},
   "source": [
    "## Discrete data\n",
    "\n",
    "### Construction\n",
    "\n",
    "As mentioned in the introduction, the `GenericSeries` can either describe a dimension dependent quantity by a set of discrete values or a mathematical expression.\n",
    "We will start this tutorial with discrete values.\n",
    "\n",
    "Let's say we want to describe the temperature of a specimen along our welding groove during a single pass welding experiment.\n",
    "The spatial direction along the groove is the dimension `x`.\n",
    "Time is represented by the dimension `t`.\n",
    "We have measured the temperature at 4 different points in time and at 6 different positions.\n",
    "Our data measured in Kelvin is:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a5687692",
   "metadata": {},
   "outputs": [],
   "source": [
    "t_0 = [300, 300, 300, 300, 300, 300]\n",
    "t_1 = [800, 1200, 400, 300, 300, 300]\n",
    "t_2 = [450, 500, 600, 800, 1200, 400]\n",
    "t_3 = [412, 425, 450, 500, 600, 800]\n",
    "\n",
    "data = Q_([t_0, t_1, t_2, t_3], \"K\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fa70702d",
   "metadata": {},
   "source": [
    "We also know the coordinates of the data in `x` and `t`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d75535bc",
   "metadata": {},
   "outputs": [],
   "source": [
    "coords_t = Q_([0, 10, 20, 30], \"s\")\n",
    "coords_x = Q_([0, 5, 10, 15, 20, 25], \"cm\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ab23c771",
   "metadata": {},
   "source": [
    "Here is a quick plot of our temperature data:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e79e8109",
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.plot(coords_x.m, np.transpose(data.m), label=[f\"t={v}\" for v in coords_t])\n",
    "plt.gca().legend()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "72b281c8",
   "metadata": {},
   "source": [
    "Now we can create our `GenericSeries` as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c6a686a8",
   "metadata": {},
   "outputs": [],
   "source": [
    "gs_discrete = GenericSeries(\n",
    "    obj=data, dims=[\"t\", \"x\"], coords={\"t\": coords_t, \"x\": coords_x}\n",
    ")\n",
    "gs_discrete"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b6c10c1c",
   "metadata": {},
   "source": [
    "The first argument is the raw data.\n",
    "`dims` expects a list of strings that we can use to give our dimensions names.\n",
    "With `coords` we provide the coordinates of our discrete values.\n",
    "`dims` and `coords` are optional.\n",
    "If you don't provide dimension names, the `GenericSeries` will use default names:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ad248f41",
   "metadata": {},
   "outputs": [],
   "source": [
    "GenericSeries(obj=data).dims"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "78bd07fd",
   "metadata": {},
   "source": [
    "If you are already familiar with the `xarray` python package, you might have noticed the similarities between the construction of a `GenericSeries` and an `xarray.DataArray`.\n",
    "In fact, the discrete version of the `GenericSeries` is based on an `xarray.DataArray` and they share some interfaces with comparable behavior."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "077d637c",
   "metadata": {},
   "source": [
    "## Evaluation/Interpolation\n",
    "\n",
    "Even though the `GenericSeries` might be based on discrete values, you should think of it as some kind of mathematical function object that can be evaluated at any coordinate along its dimensions.\n",
    "To do so, we simply use the call operator `()` on our `GenericSeries` and specify the coordinates we are interested in.\n",
    "For example, we might be interested in the temperature at $x=12cm$ and $t=24s$.\n",
    "The coordinates are passed as keyword arguments where the key is the dimension and the value are the coordinates we are interested in:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "91392645",
   "metadata": {},
   "outputs": [],
   "source": [
    "gs_discrete(t=\"0.25mins\", x=\"120mm\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3adfff4c",
   "metadata": {},
   "source": [
    "It is not necessary to provide coordinates for all dimensions.\n",
    "A single dimension is already enough:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9ded7e6e",
   "metadata": {},
   "outputs": [],
   "source": [
    "gs_discrete(t=\"24s\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fdcbe3ae",
   "metadata": {},
   "source": [
    "Of course, we can also evaluate multiple coordinate values for each dimension:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "55b054fd",
   "metadata": {},
   "outputs": [],
   "source": [
    "gs_discrete(t=Q_([11, 23], \"s\"), x=Q_([3, 14, 22], \"cm\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d8407f18",
   "metadata": {},
   "source": [
    "You may have noticed that we exclusively used coordinate values that do not match the coordinates we initially provided to the `GenericSeries`.\n",
    "The actual data values are obtained by interpolation.\n",
    "By default, the `GenericSeries` uses linear interpolation.\n",
    "It can be changed during construction using the `interpolation` parameter or by assigning a new value using the `interpolation` setter:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c795143b",
   "metadata": {},
   "outputs": [],
   "source": [
    "gs_discrete.interpolation = \"linear\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a6cc1a37",
   "metadata": {},
   "source": [
    "In case the provided interpolation coordinates exceed the coordinate range of the series, the corresponding result value will be set to the closest boundary value.\n",
    "\n",
    "Let's interpolate the data for $t=15s$ and plot it together with the two closest timesteps:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0cced1fa",
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.plot(coords_x.m, np.transpose(gs_discrete(t=\"15s\").data[0].m), label=\"t=15s\")\n",
    "plt.plot(\n",
    "    coords_x.m,\n",
    "    np.transpose(gs_discrete.data[1:3].m),\n",
    "    label=[f\"t={v}s\" for v in gs_discrete.data_array.t[1:3].data],\n",
    ")\n",
    "plt.gca().legend();"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "71638a0f",
   "metadata": {},
   "source": [
    "As one might expect the linearly interpolated data is the mean value of both curves since $t=15s$ lies directly in the middle between $t=10s$ and $t=20s$.\n",
    "However, that doesn't really look like the correct temperature distribution for a single torch moving along the groove.\n",
    "Instead the peak value should translate from left to right.\n",
    "Of cause, with dense data from real measurements, this would be just a minor issue with no practical relevance, but it serves as a nice transition two our next topic."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c125a374",
   "metadata": {},
   "source": [
    "## Using Expressions\n",
    "\n",
    "### A simple example\n",
    "\n",
    "Another way to define a `GenericSeries` is using mathematical expressions.\n",
    "In contrast to the previously shown approach we do not need to generate and store a lot of discrete data.\n",
    "All we need is a simple formula.\n",
    "Additionally, we do not get interpolation errors as in the previous section since we can evaluate the expression exactly for any given set of coordinates.\n",
    "\n",
    "Let's start with a more or less simple example where we try to depict the data from the previous section as an expression.\n",
    "Note that we are not thriving for an exact match of the values, since this is only an example of the `GenericSeries`'s features.\n",
    "The following equation resembles a single wave that travels towards increasing $x$ values with increasing v $t$:\n",
    "\n",
    "$$\n",
    "f\\left(x,t\\right)=\\mathrm{tanh}\\left(\\frac{x-t}{5}\\right) - \\mathrm{tanh}\\left(x-t-10\\right)\n",
    "$$\n",
    "\n",
    "Like in the previous section, the slope on the right-hand side of the peak is much steeper.\n",
    "We now translate this equation into an expression string that can be understood by the `GenericSeries`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c1708ad4",
   "metadata": {},
   "outputs": [],
   "source": [
    "expr = \"tanh((x-t)/5) - tanh(x-t-10)\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8e8701e7",
   "metadata": {},
   "source": [
    "The syntax is pretty close to python code, except that it is enclosed inside of a string.\n",
    "Now we could create a `MathematicalExpression` using this expression string and pass it to the `GenericSeries`, but it is much easier to simply pass the string directly to the `GenericSeries`:\n",
    "\n",
    "> TODO Link MathExpr tutorial"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "af9a9c78",
   "metadata": {},
   "outputs": [],
   "source": [
    "gs_expr = GenericSeries(expr)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e8d32047",
   "metadata": {},
   "source": [
    "We have now created a `GenericSeries` based on an expression.\n",
    "Wasn't that hard, right?\n",
    "Let's print it and have a look at its representation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c445e023",
   "metadata": {},
   "outputs": [],
   "source": [
    "gs_expr"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2df21aa2",
   "metadata": {},
   "source": [
    "The first item of the output is the expression we entered, but there are also the fields `Parameters`, `Dimensions`, and `Units`.\n",
    "Our current `GenericSeries` has no parameters (see terminology at the beginning) since we did not define any so far.\n",
    "The dimensions `x` and `t` were automatically extracted from the provided expression.\n",
    "The field `Units` refers to the units our quantity after we evaluated the expression.\n",
    "As you can see, the field is currently empty and we will soon understand why this is the case.\n",
    "But first, we will evaluate our equation as we did before with the discrete version, except that we will not use units here.\n",
    "Again, we will talk about this later."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "086d0663",
   "metadata": {},
   "outputs": [],
   "source": [
    "coords_t = [-5, 5, 15]\n",
    "coords_x = list(range(25))\n",
    "result = gs_expr(t=coords_t, x=coords_x)\n",
    "result"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ebd82a5e",
   "metadata": {},
   "source": [
    "The result is a new `GenericSeries` with discrete values at the coordinates we provided.\n",
    "Let's create a plot from the data:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "53933b80",
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.plot(\n",
    "    result.data_array.x,\n",
    "    np.transpose(result.data.m),\n",
    "    label=[f\"t={v}\" for v in result.data_array.t.data],\n",
    ")\n",
    "plt.gca().legend();"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4462d8c7",
   "metadata": {},
   "source": [
    "### Adding parameters\n",
    "\n",
    "While we can already recognize in the previous plot, that it has some similarities with the plot of the discrete data, a look at the y-axis tells us, that the magnitudes do not match.\n",
    "We will correct this by multiplying with a scaling factor `s` and adding an offset `o`.\n",
    "The new expression is:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "59af18af",
   "metadata": {},
   "outputs": [],
   "source": [
    "expr_param = \"s * (tanh((x-t)/5) - tanh(x-t-10)) + o\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ba1da5c9",
   "metadata": {},
   "source": [
    "So far, there is nothing that distinct `s` and `o` from `x` and `t`.\n",
    "They are just another set of symbols in our equation.\n",
    "We will declare `s` and `o` as expression parameters during the construction of our `GenericSeries` using the `parameters` argument.\n",
    "It expects a dictionary, that maps a discrete value to any of our expressions symbols.\n",
    "Let us now do this for `s` and `o`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "19bb082b",
   "metadata": {},
   "outputs": [],
   "source": [
    "gs_expr_param = GenericSeries(\n",
    "    expr_param,\n",
    "    parameters=dict(s=450, o=300),\n",
    ")\n",
    "gs_expr_param"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ce35e742",
   "metadata": {},
   "source": [
    "As you can see, `s` and `o` now appear in the `Parameters` section together with the values we assigned to them while `t` and `x` are still variables.\n",
    "If we plot the new `GenericSeries` at the same coordinates as before, we can see the effect of our modifications on the y-axis:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c3489b70",
   "metadata": {},
   "outputs": [],
   "source": [
    "result_expr_param = gs_expr_param(t=coords_t, x=coords_x)\n",
    "plt.plot(\n",
    "    coords_x,\n",
    "    np.transpose(result_expr_param.data.m),\n",
    "    label=[f\"t={v}\" for v in coords_t],\n",
    ")\n",
    "plt.gca().legend();"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "66bfdacf",
   "metadata": {},
   "source": [
    "### Adding units"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "02d59b8f",
   "metadata": {},
   "source": [
    "The final piece we are missing in resembling the discrete data as expression are units.\n",
    "We avoided them so far, so that you don't get overwhelmed with information and learn things step by step.\n",
    "Adding units is pretty simpel, but you need to watch out that the provided units are actually compatible in context of the expression.\n",
    "\n",
    "Looking at our equation, $x-t$ already violates this constraint since we can't subtract a time from a length.\n",
    "It only worked in the previous examples because we didn't provide any units at all.\n",
    "Note that plain numbers are silently converted to unitless quantities.\n",
    "Furthermore, the hyperbolic tangent requires an angular unit.\n",
    "Python let's us actually get away with unitless quantities as inputs to the hyperbolic tangent and treats them as radians, but you should not rely on this and always use the correct units.\n",
    "\n",
    "We can solve these aforementioned issues by simply introducing additional unit conversion parameters.\n",
    "In our example expression, we introduce the additional parameters `a` and `b` to multiply them with with `x` and `t` so that the addition is valid and yields an angular unit.\n",
    "The updated expression now looks like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d2298303",
   "metadata": {},
   "outputs": [],
   "source": [
    "expr_units = \"s * (tanh((a*x-b*t)/5) - tanh(a*x-b*t-10)) + o\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1eb609e5",
   "metadata": {},
   "source": [
    "We define the values for the parameters as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "662ae94c",
   "metadata": {},
   "outputs": [],
   "source": [
    "params_units = dict(s=\"450K\", o=\"300K\", a=\"rad/cm\", b=\"rad/s\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2fcbad50",
   "metadata": {},
   "source": [
    "Note that we added Kelvins as units to `s` and `o`.\n",
    "If we now try to create a new, updated `GenericSeries`, we will still get an error:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "15e3a33d",
   "metadata": {},
   "outputs": [],
   "source": [
    "try:\n",
    "    GenericSeries(expr_units, parameters=params_units)\n",
    "except DimensionalityError:\n",
    "    print(\"Still got an issue with the dimensions!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0a0b179c",
   "metadata": {},
   "source": [
    "The remaining problem here is that the `GenericSeries` doesn't know the units of our dimensions `x` and `t`.\n",
    "Because we didn't specify that, it assumes they are dimensionless.\n",
    "We can tell the `GenericSeries` what units those dimensions have by using the `units` input during initialization.\n",
    "It requires a simple mapping between the dimension and its unit like in the following example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c4400dba",
   "metadata": {},
   "outputs": [],
   "source": [
    "gs_units = GenericSeries(expr_units, parameters=params_units, units=dict(x=\"cm\", t=\"s\"))\n",
    "gs_units"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5d754ecf",
   "metadata": {},
   "source": [
    "> **Additional note:** Actually, the `GenericSeries` doesn't require a unit for a dimension, but a \"dimensionality\" like length, time, temperature etc. It has no real relevance if you would assign seconds, minutes or hours to a dimension since the unit will be scaled internally\n",
    "\n",
    "Finally, we are able to construct our `GenericSeries` that also considers units.\n",
    "As you can see, all the provided units are now listed in the output above.\n",
    "Additionally, the output unit of the expression is listed as Kelvin under `Units` even though it was never explicitly specified.\n",
    "The `GenericSeries` is able to determine it on its own from the information it already has.\n",
    "\n",
    "If we now want to evaluate the expression, we also have to provide the coordinates as quantities with a fitting unit, otherwise we get an error as the following example shows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "01688660",
   "metadata": {},
   "outputs": [],
   "source": [
    "coords_t = [-5, 5, 15]\n",
    "coords_x = [5, 10, 25]\n",
    "try:\n",
    "    gs_units(t=coords_t, x=coords_x)\n",
    "except DimensionalityError:\n",
    "    print(\"You forgot the units!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "454d9103",
   "metadata": {},
   "source": [
    "Adding the correct units fixes the problem:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ff9a4f65",
   "metadata": {},
   "outputs": [],
   "source": [
    "coords_t = Q_([-5, 5, 15], \"h\")\n",
    "coords_x = Q_([5, 10, 25], \"km\")\n",
    "\n",
    "gs_units(t=coords_t, x=coords_x)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b0c32445",
   "metadata": {},
   "source": [
    "In case you wonder, why all the output values are identical, have a look at the input units we used.\n",
    "If you change them to `\"s\"` and `\"cm\"` you will see values that are more in line with the previous examples, but they demonstrate that it is not important which units you assign to the dimensions during initialization.\n",
    "All that matters is the units \"dimensionality\"."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f0b60656",
   "metadata": {},
   "source": [
    "### Parameter dimensions\n",
    "\n",
    "When we discussed the terminology, we stated that all variables of an expression based `GenericSeries` are dimensions, but not all dimensions are variables.\n",
    "We will now show you a dimension that is not a variable using a short example.\n",
    "Consider the following linear equation:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fe317b17",
   "metadata": {},
   "outputs": [],
   "source": [
    "expr_linear = \"a*t + b\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0ab6f1a0",
   "metadata": {},
   "source": [
    "`t` is our only variable and represents time.\n",
    "`a` and `b` are parameters.\n",
    "So far we only used scalar parameters, but nothing hinders us to use arrays as well:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "78d06501",
   "metadata": {},
   "outputs": [],
   "source": [
    "GenericSeries(\n",
    "    expr_linear,\n",
    "    parameters=dict(a=Q_([1, 3, 5], \"m/s\"), b=Q_([5, 6, 7], \"m\")),\n",
    "    units=dict(t=\"s\"),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5d10940b",
   "metadata": {},
   "source": [
    "In the output above, we notice that we got an additional dimension we did not define: `dim_0`.\n",
    "This happened because we used arrays for our parameters.\n",
    "An array is another dimension with discrete values.\n",
    "Since we did not define a dimension name, the `GenericSeries` assigned one itself, `dim_0`.\n",
    "It also assumes that all provided parameters share the same dimensions.\n",
    "But that doesn't have to be what we intended.\n",
    "Maybe we wanted `a` and `b` to have different dimensions.\n",
    "Therefore, we can also assign dimensions to parameters.\n",
    "This can either be done by providing the parameter as a tuple consisting of value and dimension name or as an `xarray.DataArray`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6d6f8410",
   "metadata": {},
   "outputs": [],
   "source": [
    "a = (Q_([1, 3, 5], \"m/s\"), \"c\")\n",
    "b = DataArray(Q_([5, 6, 7], \"m\"), dims=[\"v\"])\n",
    "\n",
    "gs_array = GenericSeries(\n",
    "    expr_linear,\n",
    "    parameters=dict(a=a, b=b),\n",
    "    units=dict(t=\"s\"),\n",
    ")\n",
    "gs_array"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "da238f48",
   "metadata": {},
   "source": [
    "As you can see, we now have three dimensions, while only one is an actual variable of our expression.\n",
    "If we evaluate the `GenericSeries`, the dimensions will be broadcastet and our result will be a new 3 dimensional discrete `GenericSeries`.\n",
    "But see for yourself:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "dd93cb6d",
   "metadata": {},
   "outputs": [],
   "source": [
    "gs_array(t=Q_([0, 1], \"s\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4a2dc936",
   "metadata": {},
   "source": [
    "Parameters can also have more than one dimension:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c89123e3",
   "metadata": {},
   "outputs": [],
   "source": [
    "GenericSeries(\n",
    "    expr_linear,\n",
    "    parameters=dict(\n",
    "        a=Q_([[0, 1], [2, 3]], \"m/s\"),\n",
    "        b=Q_([1, 2], \"m\"),\n",
    "    ),\n",
    "    units=dict(t=\"s\"),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5006db5f",
   "metadata": {},
   "source": [
    "Note that if you do not provide custom names for the dimensions, the `GenericSeries` will just enumerate them as in the example above.\n",
    "The enumeration is always restarted for each parameter. \n",
    "So `b` would actually use the dimension `dim_0`.\n",
    "To avoid any problems, always name your dimensions.\n",
    "If you use a tuple to name the dimensions of a multi-dimensional parameter, the second value has to be a list of names, where the first name refers to the most outer dimension and the last one to the most inner:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fde35b19",
   "metadata": {},
   "outputs": [],
   "source": [
    "GenericSeries(\n",
    "    expr_linear,\n",
    "    parameters=dict(\n",
    "        a=(Q_([[0, 1], [2, 3]], \"m/s\"), [\"c\", \"v\"]), b=(Q_([1, 2], \"m\"), \"v\")\n",
    "    ),\n",
    "    units=dict(t=\"s\"),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3392d10d",
   "metadata": {},
   "source": [
    "### Partial evaluation\n",
    "\n",
    "Like a `GenericSeries` constructed from discrete values, an expression based `GenericSeries` can also be evaluated partially.\n",
    "Here is a short example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "60d221c9",
   "metadata": {},
   "outputs": [],
   "source": [
    "gs_reduced = gs_units(t=Q_([5, 10, 15], \"s\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4808257d",
   "metadata": {},
   "source": [
    "In this case, we get a new expression-based `GenericSeries`.\n",
    "`t` now becomes a new parameter consisting of the provided values.\n",
    "As long as we do not provide coordinates for all variables of an expression, evaluating the `GenericSeries` will transform the corresponding variables into parameters.\n",
    "Only if all variables get coordinates assigned to them, the resulting `GenericSeries` will consist of discrete data.\n",
    "Let's evaluate the result from the previous evaluation to confirm this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "456fed6f",
   "metadata": {},
   "outputs": [],
   "source": [
    "gs_reduced(x=\"5cm\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "",
   "language": "python",
   "name": ""
  },
  "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.8.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}