.. _DataSeries:

================================================================================
DataSeries
================================================================================
Group for TimeSeries models.

Available models:
TimeSeries_

.. _TimeSeries:

--------------------------------------------------------------------------------
TimeSeries
--------------------------------------------------------------------------------
Model for applying time-series data.

A TimeSeries device takes a `xlsx` data spreadsheet and applies the data to
the specified device. The spreadsheet can contain multiple sheets, each with
a column named ``t`` and multiple user-defined columns for the data. The
values will be applied at the exact time instant.

The ``xlsx`` data spreadsheet is assumed in the same folder as the case
file.

Regarding the parameters for the ``TimeSeries`` device:

- The column names in the ``xlsx`` data file need to be specified through
  the ``fields`` parameter, separated by commas.
- The parameter/service names of the device which is to be updated need to
  be specified through the ``dests`` parameter, separated by commas.

There are a few caveats with the current TimeSeries implementation:

- TimeSeries will not be applied power flow.
- The interpolation mode has yet to be implemented.

Parameters
----------

+---------+-----------+--------------------------------------------------------------+---------+--------+------------+
|  Name   |  Symbol   |                         Description                          | Default |  Unit  | Properties |
+=========+===========+==============================================================+=========+========+============+
|  idx    |           | unique device idx                                            |         |        |            |
+---------+-----------+--------------------------------------------------------------+---------+--------+------------+
|  u      | :math:`u` | connection status                                            | 1       | *bool* |            |
+---------+-----------+--------------------------------------------------------------+---------+--------+------------+
|  name   |           | device name                                                  |         |        |            |
+---------+-----------+--------------------------------------------------------------+---------+--------+------------+
|  mode   |           | Mode for applying timeseries. 1: exact time, 2: interpolated | 1       |        |            |
+---------+-----------+--------------------------------------------------------------+---------+--------+------------+
|  path   |           | Path to timeseries xlsx file.                                |         |        | mandatory  |
+---------+-----------+--------------------------------------------------------------+---------+--------+------------+
|  sheet  |           | Sheet name to use                                            |         |        | mandatory  |
+---------+-----------+--------------------------------------------------------------+---------+--------+------------+
|  fields |           | comma-separated field names in timeseries data               |         |        | mandatory  |
+---------+-----------+--------------------------------------------------------------+---------+--------+------------+
|  tkey   |           | Key for timestamps                                           | t       |        |            |
+---------+-----------+--------------------------------------------------------------+---------+--------+------------+
|  model  |           | Model to link to                                             |         |        | mandatory  |
+---------+-----------+--------------------------------------------------------------+---------+--------+------------+
|  dev    |           | Idx of device to link to                                     |         |        | mandatory  |
+---------+-----------+--------------------------------------------------------------+---------+--------+------------+
|  dests  |           | comma-separated device fields as destinations                |         |        | mandatory  |
+---------+-----------+--------------------------------------------------------------+---------+--------+------------+

Discretes
-----------

+------+------------+----------+---------------+
| Name |   Symbol   |   Type   |     Info      |
+======+============+==========+===============+
|  SW  | :math:`SW` | Switcher | mode switcher |
+------+------------+----------+---------------+


Config Fields in [TimeSeries]

+---------------+--------+-------+-----------------------------------------+-----------------+
|    Option     | Symbol | Value |                  Info                   | Accepted values |
+===============+========+=======+=========================================+=================+
|  allow_adjust |        | 1     | allow adjusting upper or lower limits   | (0, 1)          |
+---------------+--------+-------+-----------------------------------------+-----------------+
|  adjust_lower |        | 0     | adjust lower limit                      | (0, 1)          |
+---------------+--------+-------+-----------------------------------------+-----------------+
|  adjust_upper |        | 1     | adjust upper limit                      | (0, 1)          |
+---------------+--------+-------+-----------------------------------------+-----------------+
|  silent       |        | 1     | suppress output messages if is not zero | (0, 1)          |
+---------------+--------+-------+-----------------------------------------+-----------------+