Datatypes

Txy

The Txy datatype is used for 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.

Txy datatype

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”.

Example usage of Txy for a dc-line

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: Time in the LtmApi.

Example for setting a constant value with optional timestamps is shown below.

Constant value Txy for a dc-line

Example
"forward_capacity": { "scenarios": [ [ 20 ] ] }

TxyLin

It is recommend to the read the LTM-core documentation for the piecewise linear Time dependent constraints.

The TxyLin datatype is used for specifying Time dependent piecewise linear constraints. TxyLin input is idential to the Txy, 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!

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:

"external_reference": {
    "type": "hdf5",
    "filename": "path/source.hdf5",
    "path": "internal/hdf5/path"
}

"external_reference": {
    "type": "sqlite",
    "filename": "sqlite.db",
    "path": "table_name"
}

"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

The xy datatype includes the following input. The parameters in bold are required.

xy datatype

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

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.

water_value datatype

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

"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

The reservoir_type are used on the Reservoir objects to select the type of reservoir. The options are “BUFFER” or “REGULATION” reservoirs. The buffer and regulation reservoirs are described Reservoir types.

"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

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 EMPS model strategy and 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.

feedback_factors

Parameter	Type	Description
feedback_factor	Txy	Adjusts the area load (firm power). Increase the feedback factor to increase the simulated reservoir levels for an area and vice versa.
form_factor	Txy	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	Txy	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.

"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
        }
    }
]