{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Describing measurements"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import pandas as pd\n",
    "\n",
    "import weldx\n",
    "import weldx.measurement as msm\n",
    "import weldx.transformations as tf\n",
    "from weldx import Q_\n",
    "from weldx.welding.util import sine"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Overview\n",
    "In this short example we use welding voltage and current measurements to show how to describe and store measurements with associated measurement chains. This includes describing the measurement equipment and its metadata, describing all the relevant transformation steps from raw-data to the final output and the data itself. The final result is a `MeasurementChain` that should be easy to follow and represent the complete data processing pipeline."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Generating the measurement data\n",
    "We start by creating some \"dummy\" datasets that represent the current and voltage measurements.\n",
    "In a real application, these would be the datasets that we would copy from our measurement equipment (e.g. downloaded form a HKS-WeldQAS, oscilloscope or similar systems).\n",
    "The values in this dataset represent the actual physical current and voltage data in A and V."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "time = pd.timedelta_range(start=\"0s\", end=\"10s\", freq=\"1ms\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "pycharm": {
     "is_executing": true
    }
   },
   "outputs": [],
   "source": [
    "I_ts = sine(f=Q_(10, \"1/s\"), amp=Q_(20, \"A\"), bias=Q_(300, \"A\"))\n",
    "I = I_ts.interp_time(time)  # noqa: E741\n",
    "\n",
    "current_data = weldx.TimeSeries(data=I.data, time=time)\n",
    "current_data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "U_ts = sine(f=Q_(10, \"1/s\"), amp=Q_(3, \"V\"), bias=Q_(40, \"V\"), phase=Q_(0.1, \"rad\"))\n",
    "U = U_ts.interp_time(time)\n",
    "\n",
    "voltage_data = weldx.TimeSeries(data=U.data, time=time)\n",
    "voltage_data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is important to note the type and structure of the `current_data` and `voltage_data` datasets:\n",
    "\n",
    "- they are created as `TimeSeries`\n",
    "- the data itself is a `pint.Quantity` i.e. a numpy array with associated unit. For the current measurement this is `ampere`, the voltage is given in `volt`. Using quantities is an important core concept of measurements !\n",
    "- each `TimeSeries` has a `time` dimension and coordinate using numpy datetime formats."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Equipment and Software\n",
    "Next, let's define some equipment and software that is used throughout the measurement chain.\n",
    "We will use and add more information to these objects later.\n",
    "In out example, two types of hardware equipment are used:\n",
    "\n",
    "- The [`HKS P1000-S3`](https://hks-prozesstechnik.de/en/sensors-2/) is a standard welding process sensor that detects the welding voltage and current using a hall sensor. The result is output as two analog signals scaled to +/- 10 V.\n",
    "- The [`Beckhoff ELM3002-0000`](https://www.beckhoff.com/ELM3002/) is a fieldbus AD-converter terminal that picks up the analog signals of the HKS Sensor and transmits them digitally to the control software.\n",
    "\n",
    "The final piece involved in the measurement chain is the Software used to record, scale and save both the welding current and voltage measurements. We define the software version and name used during the example using built-in ASDF types."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "HKS_sensor = msm.MeasurementEquipment(name=\"HKS P1000-S3\")\n",
    "\n",
    "BH_ELM = msm.MeasurementEquipment(name=\"Beckhoff ELM3002-0000\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from asdf.tags.core import Software\n",
    "\n",
    "twincat_scope = Software(name=\"Beckhoff TwinCAT ScopeView\", version=\"3.4.3143\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Defining a measurement chain: current measurement\n",
    "Now we define the missing elements of our measurement chain and bundle everything together. A core concept of the chain are `signals` that go in and out of `transformations` which define mathematical operations of the signals, forming the chain.\n",
    "\n",
    "Each measurement chain starts with a source signal. This is the point where our physical process or quantity is initially detected by a sensor. Since every `MeasurementChain` needs at least a source, we need to provide the corresponding information when creating an instance of this class. \n",
    "As shown in the [tutorial about the measurement chain class](measurement_chain.ipynb), there are several ways to do this.\n",
    "Because we have already defined our source equipment, we will add the `SignalSource` to the `MeasurementEquipment` and use it to create our `MeasurementChain`. \n",
    "The necessary parameters to create the `SignalSource` are its `name`, the `output_signal` and the `source_error` representing the uncertainty attached to the signal source. \n",
    "\n",
    "For our current measurement, the source outputs an **analog Signal** of unit **V**. \n",
    "According to the spec sheet of the sensor the measurement error in this initial step is **0.1 %** which can be documented using the `Error` property (again using quantities)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "current_source = msm.SignalSource(\n",
    "    name=\"Current sensor\",\n",
    "    error=msm.Error(Q_(0.1, \"percent\")),\n",
    "    output_signal=msm.Signal(signal_type=\"analog\", units=\"V\"),\n",
    ")\n",
    "\n",
    "HKS_sensor.sources.append(current_source)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we can create the current measurement chain. Since there is no recording of this measurement we do not provide any data. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "welding_current_chain = msm.MeasurementChain.from_equipment(\n",
    "    name=\"welding current measurement chain\",\n",
    "    equipment=HKS_sensor,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The next step in the chain is picking up the analog voltage signal from our source with the Beckhoff AD converter terminal which transform the signal into an internal signed integer value. The formula describing this linear transformation with input `x` is\n",
    "```\n",
    "a * x + b\n",
    "32768 / (10 V) * x  + 0\n",
    "```\n",
    "We express this signal transformation as an analytical formula. Based on the above formula we also define the static parameters `a` and `b` in the `MathematicalExpression`. Note that we use quantities here as well!\n",
    "Since our result is a dimensionless integer `a` has the unit **1/V** and `b` is dimensionless which we indicate with `\"\"`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from weldx.tags.core.mathematical_expression import MathematicalExpression\n",
    "\n",
    "current_AD_func = MathematicalExpression(\n",
    "    expression=\"a * x + b\", parameters=dict(a=Q_(32768.0 / 10.0, \"1/V\"), b=Q_(0.0, \"\"))\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that we have the transform function we can define our `SignalTransformation`.\n",
    "Our new Transformation outputs a new **dimensionless** signal of type **digital**.\n",
    "The Beckhoff AD converter lists the measurement Error at **0.01 %**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "current_AD_transform = msm.SignalTransformation(\n",
    "    name=\"AD current\",\n",
    "    func=current_AD_func,\n",
    "    type_transformation=\"AD\",\n",
    "    error=msm.Error(Q_(0.01, \"percent\")),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We add the transformation to our `MeasurementEquipment` representing the Beckhoff AD converter."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "BH_ELM.transformations.append(current_AD_transform)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next we use the equipment to add the transformation to the measurement chain."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "welding_current_chain.add_transformation_from_equipment(BH_ELM)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Similar to the AD conversion, we add the final step of our signal processing chain: digitally converting the signal to the final physical representation of the welding current. The current calibration formula from our integer values to the real current values is as follows:\n",
    "```\n",
    "1000 A / 32768 * x  + 0 A\n",
    "```\n",
    "Put into a new `sympy` expression:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# define current output calibration expression and transformation\n",
    "current_calib_func = MathematicalExpression(\n",
    "    \"a * x + b\", parameters=dict(a=Q_(1000.0 / 32768.0, \"A\"), b=Q_(0.0, \"A\"))\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We create the final transformation step:\n",
    "\n",
    "- the output signal is our final current measurement representation\n",
    "- we add the our measurement data to this signal !\n",
    "- we add the software as a meta field to the signal transformation, since the `Software` class currently does not provide the option to store transformations and therefore can't be linked automatically by the `MeasurementChain`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "current_calib_transform = msm.SignalTransformation(\n",
    "    name=\"calibration current\",\n",
    "    error=msm.Error(0.0),\n",
    "    func=current_calib_func,\n",
    "    meta=twincat_scope,\n",
    ")\n",
    "\n",
    "welding_current_chain.add_transformation(\n",
    "    transformation=current_calib_transform, data=current_data\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that our `MeasurementChain` is complete, we can visualize it using its `plot` function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "welding_current_chain.plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally the `Measurement` is our measurement chain with another link to the data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "welding_current = msm.Measurement(\n",
    "    name=\"welding current measurement\",\n",
    "    data=[current_data],\n",
    "    measurement_chain=welding_current_chain,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## voltage measurement\n",
    "We follow the same procedure described in the current measurement here :-)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "voltage_source = msm.SignalSource(\n",
    "    name=\"Voltage sensor\",\n",
    "    error=msm.Error(Q_(0.1, \"percent\")),\n",
    "    output_signal=msm.Signal(signal_type=\"analog\", units=\"V\"),\n",
    ")\n",
    "\n",
    "HKS_sensor.sources.append(voltage_source)\n",
    "\n",
    "welding_voltage_chain = msm.MeasurementChain.from_equipment(\n",
    "    name=\"welding voltage measurement\",\n",
    "    equipment=HKS_sensor,\n",
    "    source_name=\"Voltage sensor\",\n",
    ")\n",
    "\n",
    "\n",
    "voltage_ad_func = MathematicalExpression(\n",
    "    \"a * x + b\", parameters=dict(a=Q_(32768.0 / 10.0, \"1/V\"), b=Q_(0.0, \"\"))\n",
    ")\n",
    "\n",
    "voltage_AD_transform = msm.SignalTransformation(\n",
    "    name=\"AD voltage\",\n",
    "    error=msm.Error(Q_(0.01, \"percent\")),\n",
    "    func=voltage_ad_func,\n",
    "    type_transformation=\"AD\",\n",
    ")\n",
    "\n",
    "BH_ELM.transformations.append(voltage_AD_transform)\n",
    "\n",
    "welding_voltage_chain.add_transformation_from_equipment(\n",
    "    equipment=BH_ELM, transformation_name=\"AD voltage\"\n",
    ")\n",
    "\n",
    "\n",
    "# define voltage output calibration expression and transformation\n",
    "voltage_calib_func = MathematicalExpression(\n",
    "    expression=\"a * x + b\", parameters=dict(a=Q_(100.0 / 32768.0, \"V\"), b=Q_(0.0, \"V\"))\n",
    ")\n",
    "\n",
    "voltage_calib_transform = msm.SignalTransformation(\n",
    "    name=\"calibration voltage\",\n",
    "    error=msm.Error(0.0),\n",
    "    func=voltage_calib_func,\n",
    "    meta=twincat_scope,\n",
    ")\n",
    "\n",
    "welding_voltage_chain.add_transformation(\n",
    "    transformation=voltage_calib_transform,\n",
    "    data=voltage_data,\n",
    ")\n",
    "\n",
    "\n",
    "welding_voltage = msm.Measurement(\n",
    "    name=\"welding voltage measurement\",\n",
    "    data=[voltage_data],\n",
    "    measurement_chain=welding_voltage_chain,\n",
    ")\n",
    "welding_voltage_chain.plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "nbsphinx": "hidden"
   },
   "source": [
    "## Coordinate Systems\n",
    "\n",
    "Most data does not make much sense without being able to determine where it was recorded in relation to a specimen or other measurement spots. Therefore, we define coordinate systems and their orientations towards each other. The basic principles are already explained in the transformation tutorials, so we will just define some coordinate systems without further explanation. To keep things simple, no time dependent coordinates are considered."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": "hidden"
   },
   "outputs": [],
   "source": [
    "lcs_specimen_in_root = tf.LocalCoordinateSystem(\n",
    "    coordinates=Q_(np.asarray([100, 75, 0]), \"mm\")\n",
    ")\n",
    "lcs_flange_in_root = tf.LocalCoordinateSystem(\n",
    "    orientation=tf.WXRotation.from_euler(\"x\", np.pi / 2).as_matrix(),\n",
    "    coordinates=Q_(np.asarray([115, -10, 140]), \"mm\"),\n",
    ")\n",
    "lcs_torch_in_flange = tf.LocalCoordinateSystem(\n",
    "    coordinates=Q_(np.asarray([100, 75, 0]), \"mm\")\n",
    ")\n",
    "\n",
    "coordinate_systems = tf.CoordinateSystemManager(\"root\")\n",
    "coordinate_systems.add_cs(\"specimen\", \"root\", lcs_specimen_in_root)\n",
    "coordinate_systems.add_cs(\"flange\", \"root\", lcs_flange_in_root)\n",
    "coordinate_systems.add_cs(\"torch\", \"flange\", lcs_torch_in_flange)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "nbsphinx": "hidden"
   },
   "source": [
    "> **TODO:** Connect data to coordinate systems"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Writing to ASDF\n",
    "Once we have defined all object we can write them to an ASDF file. To make the file easier to read we place some elements earlier in the tree."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "equipment = [HKS_sensor, BH_ELM]\n",
    "measurement_data = [current_data, voltage_data]\n",
    "measurements = [welding_current, welding_voltage]\n",
    "\n",
    "tree = {\n",
    "    # \"coordinate_systems\": coordinate_systems,\n",
    "    \"equipment\": equipment,\n",
    "    \"data\": measurement_data,\n",
    "    \"measurements\": measurements,\n",
    "}\n",
    "file = weldx.WeldxFile(tree=tree, mode=\"rw\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "file.header()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}