========= Datatypes ========= .. _txy-label: Txy === The Txy datatype is used for :ref:`break_point_series` and includes the following input. The parameters in **bold** are required, one of the two parameters in *italics* are required and the others are optional. .. list-table:: Txy datatype :header-rows: 1 :widths: 35 25 95 * - Parameter - Type - Description * - **timestamps** - array of strings - Array of timestamps. Local timezone. * - **scenarios** - array of double - The array must be the same size as timestaps. The scenario values are active at the time specified in corresponding timestamps * - external_reference - takes attributes - Reference to external data on formats *hdf5*, *sqlite* and *csv*. Attributes: "type", "filename", "path", optional * - name - string, optional - Optional object name * - #comment - string, optional - Optional comment. * - unit - string, optional - Optional string for the unit type. Can be anything. Some examples are "NOK", "SEK", "MWh". .. list-table:: Example usage of Txy for a dc-line :header-rows: 1 :widths: 75 * - Example * - :: "forward_capacity": { "timestamps": [ "2024-01-01T00:00:00Z" ], "scenarios": [ [ 20 ] ] } Txy special cases ----------------- Two special cases exists for Txy datatype. - For defining time periods in the LtmApi *scenarios* are optional. - For defining a constant value the *timestamps* are optional Example of optional scenarios can be found here: :ref:`api_time`. Example for setting a constant value with optional timestamps is shown below. .. list-table:: Constant value Txy for a dc-line :header-rows: 1 :widths: 75 * - Example * - :: "forward_capacity": { "scenarios": [ [ 20 ] ] } .. _txylin-label: TxyLin ====== It is recommend to the read the LTM-core documentation for the piecewise linear :ref:`time_dependent_constraints`. The TxyLin datatype is used for specifying :ref:`api_time_dependent_piecewise_linear_constraints`. TxyLin input is idential to the :ref:`txy-label`, but the datapoints are linearised in the LTM-core (unlike the Txy datatype = break points series). The TxyLin datatype are used for the constaints: - min_bypass_curve - max_bypass_curve - min_discharge_curve - max_discharge_curve - min_volume_curve - max_volume_curve and for specifying the: - reference_curve TxyLin value-pairs in the TxyLin datatype referes to points which are used for linearisation, these points must be specified correctly, thus a stricter handling of the the TxyLin datatype than the Txy datatype is necessary. TxyLin requirements: - all timestamps must be **within the data_period**. Error is printed otherwise. - minimum two points are required (for linearisation). Error is printed otherwise. It is possible to set a constant value for the TxyLin datatype similar to Txy. The timestamp must start **at or before** the data_period start. A constant value means **no linearisation!** .. notice:: ``TxyLin`` is also used for cyclic linear curves: :ref:`api_cyclic_piecewise_linear_constraints`. Using *external_reference* -------------------------- Supported types are ``internal``, ``hdf5``, ``sqlite`` and ``csv``. Any other type will generate an error with the following description: :: Could not assign external_datatype from value 'does_not_exist'. Value is unrecognized. Known values are 'csv, hdf5, internal, sqlite' Examples: .. code-block:: json "external_reference": { "type": "hdf5", "filename": "path/source.hdf5", "path": "internal/hdf5/path" } .. code-block:: json "external_reference": { "type": "sqlite", "filename": "sqlite.db", "path": "table_name" } .. code-block:: json "external_reference": { "type": "csv", "filename": "path/timeseriesdata.csv" } .. note:: When ``external_reference`` is set, is it an error to have ``timestamps`` or ``scenarios`` set. External reference points to external timeseries data and will only be loaded when writing LTM files to disk. .. _xy-label: xy == The **xy** datatype includes the following input. The parameters in **bold** are required. .. list-table:: xy datatype :header-rows: 1 :widths: 35 25 95 * - Parameter - Type - Description * - **x** - array of double - Array of x with a functional relationship with y * - **y** - array of double - Array of y must have the same size as x. y-value for a given x-value. .. _water_value_weights: water_value_weights =================== The **water_value** datatype used on busbar objects for user specification of water value weights (*water_value_weights*) is optional and specialist settings. .. warning:: It requires experience to use the manual selection of scenario weights. We recommend using automatic weights which is the default setting. The **water_value_weights** includes the following input. The parameters in **bold** are required and the others are optional. .. list-table:: water_value datatype :header-rows: 1 :widths: 35 25 95 * - Parameter - Type - Description * - **weights** - Array of a pair of int, array of double - The int of the pair is the week number and the array of double of the pair contains the weights * - inflow_conditions - int - Specifies the number of inflow states .. code-block:: json "busbars": [ { "name": "numedal" }, { "#comment": "water_value_manual_weights", "name": "test_102", "water_value_weights":{ "inflow_conditions": 1, "weights":[ [18, [1.0, 5.0, 9.0, 20.0, 9.0, 5.0, 1.0]], [40, [1.0, 5.0, 9.0, 20.0, 9.0, 5.0, 1.0]], [70, [1.0, 5.0, 9.0, 20.0, 9.0, 5.0, 1.0]] ] } } ] .. _reservoir_type: reservoir_type ============== The **reservoir_type** are used on the :ref:`api_reservoir` objects to select the type of reservoir. The options are **"BUFFER"** or **"REGULATION"** reservoirs. The buffer and regulation reservoirs are described :ref:`ltm_reservoir_types`. .. code-block:: json "reservoirs": [ { "name": "upper_main", "max_volume": 100.0, "average_spill_energy_equivalent": 0.5, "reservoir_type": "REGULATION", "regulated_inflow_name": "ten", "average_regulated_inflow": 200.0, "max_discharge": 70.3, "reference_curve": { "timestamps": [ "2023-04-24T00:00:00Z", "2023-10-02T00:00:00Z", "2023-12-11T00:00:00Z" ], "scenarios": [ [ 20.0, 85.0, 75.0 ] ] } } ] .. _feedback_factors: feedback_factors ================ The **feedback_factors** are used on busbar objects for user specification of busbar feedback factors and they are optional. The feeback factors are used for :ref:`calibration` of the EMPS model in the strategy phase. .. warning:: The implementation of the busbar feedback factors are not yet finished. They require specialist experience. The **feedback_factors** includes the following input. The parameters in **bold** are required and the others are optional. The parameter **feedback_factor** is more commonly used than the **form_factor** and the **flexibility_factor**. .. list-table:: feedback_factors :header-rows: 1 :widths: 35 25 95 * - Parameter - Type - Description * - **feedback_factor** - :ref:`txy-label` - Adjusts the area load (firm power). Increase the feedback factor to increase the simulated reservoir levels for an area and vice versa. * - **form_factor** - :ref:`txy-label` - Adjusts the area load (firm power). Determines the annual distribution of the load. A factor > 1.0 increases the winter load and decreases the summer load and vice versa. * - **flexibility_factor** - :ref:`txy-label` - Adjusts occasional market. A small scaling factor will shrink the supply/demand curve, leading to denser iso-price curves and thus fewer possible outcomes for simulated reservoir development. * - inflow_conditions - int - Specifies the number of inflow states * - #comment - string, optional - Optional comment. .. code-block:: json "busbars": [ { "name": "test", "feedback_factors": { "feedback_factor": { "start_week_values": { "timestamps": [ "2000-01-02T00:00:00Z" ], "scenarios": [ [ 1.95 ] ] } }, "form_factor": { "start_week_values": { "timestamps": [ "2000-01-02T00:00:00Z" ], "scenarios": [ [ 2.65 ] ] } }, "flexibility_factor": { "start_week_values": { "timestamps": [ "2000-01-02T00:00:00Z" ], "scenarios": [ [ 3.65 ] ] } }, "conversion_limit": { "normal_value": 4.43, "value": 4.67 }, "artificial_minimum_production": 1.4 } } ]