docs: add concepts for production order, production run and product

docs/concepts.rst

@@ -32,3 +32,53 @@ Variable
 A *variable* represents a process measure of one :ref:`appliance <appliance>` of which
 timeseries data is captured and stored in the ENLYZE platform. One appliance may have
 many variables, whereas one variable is only associated with one appliance.
+
+
+.. _production_order:
+
+Production Order
+----------------
+
+A *production order* represents the goal of producing a certain quantity of a
+given :ref:`product <product>`. Production orders are usually created in an ERP
+system or MES of the customer and then synchronized into the ENLYZE platform.
+They are referenced by an identifier which oftentimes is a short combination of
+numbers and/or characters, like FA23000123 or 332554.
+
+In the ENLYZE platform, a production order always encompasses the production of
+one single :ref:`product <product>` on one single :ref:`appliance <appliance>`.
+
+
+.. _production_run:
+
+Production Run
+--------------
+
+A *production run* represents the real allocation of a :ref:`production order
+<production_order>` on an :ref:`appliance <appliance>`. Usually, the operator of
+the appliance uses some kind of interface to log the time when a certain
+production order has been worked on. A production order oftentimes is not
+allocated continously on an appliance due to interruptions like a breakdown or
+weekend. Each of these individual, continous allocations is called a *production
+run* in the ENLYZE platform. It always has a beginning and, if it's not still
+running, it also has an end. The ENLYZE platform calculates different aggregates
+from the timeseries data of the appliance for each production run.
+
+
+.. _product:
+
+Product
+-------
+
+A *product* is the output of the production process which is executed by an
+:ref:`appliance <appliance>`, driven by a :ref:`production order
+<production_order>`. In the real world, an appliance might have some additonal
+outputs, but only the main output (the product) modelled in the ENLYZE platform.
+Similarly to the production order, a product is referenced by an identifier
+originating from a system of the customer, which is synchronized into the ENLYZE
+platform.
+
+During the integration into the ENLYZE platform, the product identifier is
+chosen in such a way that :ref:`production runs <production_run>` of the same
+product are comparable with one another. This is the foundation for constantly
+improving the production of recurring products over time.

docs/models.rst

@@ -24,3 +24,15 @@ Data models
 .. autoclass:: ResamplingMethod()
     :members:
     :undoc-members:
+
+.. autoclass:: ProductionRun()
+    :members:
+    :undoc-members:
+
+.. autoclass:: OEEScore()
+    :members:
+    :undoc-members:
+
+.. autoclass:: Quantity()
+    :members:
+    :undoc-members:

pyproject.toml

@@ -14,6 +14,11 @@ readme = "README.rst"
 license = {text = "MIT"}
 authors = [{name = "ENLYZE GmbH", email = "[email protected]"},]
 requires-python = ">=3.10"
+classifiers = [
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+]
 dynamic = [
   'version',
 ]

src/enlyze/models.py

@@ -1,5 +1,5 @@
-from dataclasses import dataclass
-from datetime import date, datetime, timezone
+from dataclasses import asdict, dataclass
+from datetime import date, datetime, timedelta, timezone
 from enum import Enum
 from itertools import chain
 from typing import Any, Iterator, Optional, Sequence
@@ -197,3 +197,102 @@ def to_dataframe(self, use_display_names: bool = False) -> pandas.DataFrame:
         )
         df.index = pandas.to_datetime(df.index, utc=True, format="ISO8601")
         return df
+
+
+@dataclass(frozen=True)
+class OEEScore:
+    """Individual Overall Equipment Effectiveness (OEE) score
+
+    This is calculated by the ENLYZE Platform based on a combination of real
+    machine data and production order booking information provided by the
+    customer.
+
+    For more information, please check out https://www.oee.com
+    """
+
+    #: The score is expressed as a ratio between 0 and 1.0, with 1.0 meaning 100 %.
+    score: float
+
+    #: Unproductive time due to non-ideal production.
+    time_loss: timedelta
+
+
+@dataclass(frozen=True)
+class Quantity:
+    """Representation of a physical quantity"""
+
+    #: Physical unit of quantity
+    unit: str
+
+    #: The quantity expressed in `unit`
+    value: float
+
+
+@dataclass(frozen=True)
+class ProductionRun:
+    """Representation of a :ref:`production run <production_run>` in the ENLYZE
+    platform.
+
+    Contains details about the production run.
+
+    """
+
+    #: The UUID of the appliance the production run was exeucted on.
+    appliance: UUID
+
+    #: The average throughput of the production run excluding downtimes.
+    average_throughput: Optional[float]
+
+    #: The identifier of the production order.
+    production_order: str
+
+    #: The identifier of the product that was produced.
+    product: str
+
+    #: The begin of the production run.
+    begin: datetime
+
+    #: The end of the production run.
+    end: Optional[datetime]
+
+    #: This is the sum of scrap and yield.
+    quantity_total: Optional[Quantity]
+
+    #: The amount of product produced that doesn't meet quality criteria.
+    quantity_scrap: Optional[Quantity]
+
+    #: The amount of product produced that can be sold.
+    quantity_yield: Optional[Quantity]
+
+    #: OEE component that reflects when the appliance did not produce.
+    availability: Optional[OEEScore]
+
+    #: OEE component that reflects how fast the appliance has run.
+    performance: Optional[OEEScore]
+
+    #: OEE component that reflects how much defects have been produced.
+    quality: Optional[OEEScore]
+
+    #: Aggregate OEE score that comprises availability, performance and quality.
+    productivity: Optional[OEEScore]
+
+
+class ProductionRuns(list[ProductionRun]):
+    """Representation of multiple :ref:`production runs <production_run>`."""
+
+    def to_dataframe(self) -> pandas.DataFrame:
+        """Convert production runs into :py:class:`pandas.DataFrame`
+
+        Each row in the data frame will represent one production run.
+        The ``begin`` and ``end`` of every production run will be
+        represented as :ref:`timezone-aware <python:datetime-naive-aware>`
+        :py:class:`datetime.datetime` localized in UTC.
+
+        :returns: DataFrame with production runs
+
+        """
+
+        df = pandas.json_normalize([asdict(run) for run in self])
+        df.begin = pandas.to_datetime(df.begin, utc=True, format="ISO8601")
+        df.end = pandas.to_datetime(df.end, utc=True, format="ISO8601")
+        return df