.. _api_time: Time in the LtmApi ================== Time in the LtmApi is highly dependent on the time in the LTM-core. It is recommend to read and **understand** the section covering :ref:`ltm_time` before reading this section. Time is specified using the :ref:`txy-label`-datatype in the LtmApi. The scenarios are *optional*. Time periods are represented by an ON/OFF state (1 or 0) for each time step defined in timestamps. The simulation begins at the first timestamp, which must have an ON state (1), and runs continuously until the first OFF state (0) is encountered. Any states following the first OFF will be ignored, the simulation does not resume once stopped. If the optional scenarios are not specified the first timestamps value refers to the ON state and the second timestamps value to the OFF state. See example below for optional usage of scenarios. These are identical. .. raw:: html 

         "global_settings": {
            "name": "example ISO time",
            "data_period": {
               "timestamps": [
                  "2025-W01",
                  "2027-W01"
               ],
               "scenarios": [
                  [
                     1,
                     0
                  ]
               ]
            }
         }
               

         "global_settings": {
            "name": "example ISO time",
            "data_period": {
               "timestamps": [
                  "2025-W01",
                  "2027-W01"
               ]
            }
         }
See the section explaining :ref:`break_point_series`. Two **time concepts** are available for the timestamps, namely the: 1. **Civillian** time - Follows the `Gregorian calendar `_ 2. **ISO** time - Specifies a `ISO week date `_ based on the gregorian calender. .. _iso-week-time-label: All of the following timestamps are equal. * ``2024-12-30T00:00:00Z`` * ``2025`` * ``2025-W01`` * ``2025-W01-1`` * ``2025-W01-1T00`` * ``2025-W01-1T00:00`` Care has been taken to reject invalid timestamps. All of the following timestamps will be rejected. * ``20250`` * ``2025-W011`` * ``2025-W`` * ``2025-W22-3T`` * ``2025-W22-3T14:`` * ``2025x`` * ``2025-W`` A special case has been added to allow for cyclic curves for ``TxyLin``, :ref:`api_cyclic_piecewise_linear_constraints`, where only the year portion of the ISO week date is omitted. This will create a curve with timestamp for year 1703. * ``W01`` * ``W15`` LTM-core long-term periods -------------------------- The important long-term periods in the LTM-core are: 1. **Simulation period** 2. **Historical period** 3. **Data period** 4. **Water value period** .. _sim_period: Simulation period ~~~~~~~~~~~~~~~~~ Mandatory attribute **simulation_period** in **global_settings**. The simulation period takes a attribute-value pair with *timestamps* and *scenarios*. In the example below the simulation period is activated on 1st of January 2024 and is deactivated on 28th of December 2026, giving a simulation of 3 EFI years (156 weeks). As shown in the examples below. .. code-block:: json "global_settings": { "name": "example regular calendar", "simulation_period": { "timestamps": [ "2024-01-01T00:00:00Z", "2026-12-28T00:00:00Z" ] } } .. _hist_period: Historical period ~~~~~~~~~~~~~~~~~ Used to define the period of historical data input to the model: - inflow - temperature in addition it affect the dimensionality of the model input such as: - wind - solar - exogenous price The attribute **historical_period** in **global_settings** is mandatory. For the historical period there are three **historical_type** time variants that defines the calender system used: 1. Civillian 2. ISO 3. EFI It is not strictly required to use timestamp formats that match the selected historical_type. For example, if historical_type is "civillian", one may use 1980-W01-2 (second day of ISO week 1), which corresponds to 1980-01-01T00:00:00Z. Vice versa, if historical_type is "ISO", one may use 1979-12-31T00:00:00Z, which corresponds to 1980-W01-1. However, for consistency and to avoid confusion, it is recommended to use timestamp formats that match the chosen historical_type. The historical period must span at least 8 years and meet the following criteria: - Start and end on **1st of Jan** if *historical_type* is *civillian*. - Start and end on week **W01** if *historical_type* is *ISO*. - Start on ISO week **W01** and end on week **N*52**, where N is number of years, if *historical_type* is *EFI*. Note on historical data: Historical data refers to past energy or water inflow series. You are free to use your preferred *historical_type* for historical data, as long as it covers the entire historical_period. The historical period takes a attribute-value pair with *timestamps* and optional *scenarios*. In the example below the historical period is activated on 1st of January 1981 and is deactivated on 1st of January 1989, giving a range of 8 years. .. code-block:: json "global_settings": { "name": "example regular calendar", "historical_period": { "timestamps": [ "1981-01-01T00:00:00Z", "1989-01-01T00:00:00Z" ] } } .. _data_period: Data period ~~~~~~~~~~~ The specification of the **data_period** in **global_settings** is optional. The data period takes a attribute-value pair with *timestamps* and optional *scenarios*. **Requirements**: - The data period always start on Monday at 00:00 of week 1 of the EFI-year - The data period always end on Sunday at 24:00 (Monday 00:00) of week 52 of the EFI-year ISO time ^^^^^^^^ We recomment using the ISO time to specify the data period. In the example below the data period is activated at the beginning of first week of 2025 and is deactivated before the first week in 2027, giving a period of 2 EFI years (104 weeks). .. code-block:: json "global_settings": { "name": "example ISO time", "data_period": { "timestamps": [ "2025-W01", "2027-W01" ] } } Civillian time ^^^^^^^^^^^^^^ The calendar for January 2025 and December 2026 is shown below. We will use it to specify the dates with the civillian calendar. .. code-block:: time January 2025 | December 2026 Mo Tu We Th Fr Sa Su Week | Mo Tu We Th Fr Sa Su Week 1 2 3 4 5 1 | 1 2 3 4 5 6 49 6 7 8 9 10 11 12 2 | 7 8 9 10 11 12 13 50 13 14 15 16 17 18 19 3 | 14 15 16 17 18 19 20 51 20 21 22 23 24 25 26 4 | 21 22 23 24 25 26 27 52 27 28 29 30 31 5 | 28 29 30 31 53 Specifying the period using the civillian calendar is more complex. In the next example we want to specify the same period as in the previous example (with ISO time). The data period is activated at 00:00 on Monday 30 of December of 2025 (Monday week 1 in 2025) and is deactivated at 00:00 on Monday 28th of December 2026 (Week 52 of 2026), giving a period of 2 EFI years (104 weeks). .. code-block:: json "global_settings": { "name": "example regular calendar", "data_period": { "timestamps": [ "2024-12-30T00:00:00Z", "2026-12-28T00:00:00Z" ] } } .. _wv_period: Water value period ~~~~~~~~~~~~~~~~~~ Optional in the LtmApi. If not specified by **water_value_period** in **global_settings** it is calculated. The water value period takes a attribute-value pair with *timestamps* and *scenarios*. In the example below the water value period is activated on 1st of January 2024 and is deactivated on 28th of December 2026, giving a period of 3 EFI years (156 weeks). .. code-block:: json "global_settings": { "name": "example regular calendar", "water_value_period": { "timestamps": [ "2024-01-01T00:00:00Z", "2026-12-28T00:00:00Z" ] } } Usage examples -------------- In the following we provide some usage examples of the time concepts in the LtmApi and the LTM-core long-term periods and the LTM-core short-term period. LTM-core long-term periods ~~~~~~~~~~~~~~~~~~~~~~~~~~ Specify a simulation period from Monday 1st of January 2024, with a duration of 156 weeks or 3 EFI-years. The historical period is from 1981 to 1988 and spans 8 years. First example uses civillian (regular calendar) time as shown below. The simulation period is activated at 1st of January 2024 and deactivated at 28th of December 2026. The historical period is activated on 1st of January 1981 and is deactivated on 1st of January 1989, giving a range of 8 years. Note that for the historical period whole calendar years are specified and not EFI-years. .. code-block:: json "global_settings": { "name": "example regular calendar", "simulation_period": { "timestamps": [ "2024-01-01T00:00:00Z", "2026-12-28T00:00:00Z" ] }, "historical_period": { "timestamps": [ "1981-01-01T00:00:00Z", "1989-01-01T00:00:00Z" ] } } Second example uses the ISO week-date as shown below. The simulation period is activated the first week of 2024 and deactivated before the last week of 2027. The historical period is activated the first week of 1981 and is deactivated on the first week of 1989, giving a range of 8 years. Note again, that for the historical period whole calendar years are specified and not EFI-years. .. code-block:: json "global_settings": { "name": "example ISO week-date", "simulation_period": { "timestamps": [ "2024-W01", "2027-W01" ] }, "historical_period": { "timestamps": [ "1981-W01", "1989-W01" ] }, .. _EFI_week_api: LTM-core short-term period ~~~~~~~~~~~~~~~~~~~~~~~~~~ The LTM-core short-term periods for the EFI week are: 1. Accumulated timesteps 2. Sequential timesteps There are two ways to specify timesteps per week. Using the attributes - **intraweek_timesteps** - sequential or accumulated timesteps - **timesteps_per_week** - always sequential timesteps in global_settings. The examples below show how to specify the intraweek timesteps, for both accumulated and sequential timesteps as shown and visualised in :ref:`timesteps_per_week`. Accumulated timesteps ~~~~~~~~~~~~~~~~~~~~~ .. code-block:: json "global_settings": { "name": "example", "intraweek_timesteps": { "#comment": "1-night, 2-day, 3-evening, 4-weekend", "timestamps": [ "2023-01-02T00:00:00Z", "2023-01-02T08:00:00Z", "2023-01-02T16:00:00Z", "2023-01-03T00:00:00Z", "2023-01-03T08:00:00Z", "2023-01-03T16:00:00Z", "2023-01-04T00:00:00Z", "2023-01-04T08:00:00Z", "2023-01-04T16:00:00Z", "2023-01-05T00:00:00Z", "2023-01-05T08:00:00Z", "2023-01-05T16:00:00Z", "2023-01-06T00:00:00Z", "2023-01-06T08:00:00Z", "2023-01-06T16:00:00Z", "2023-01-07T00:00:00Z" ], "scenarios": [ [ 1, 2, 3, 1, 2, 3, 1, 2, 3, 1, 2, 3, 1, 2, 3, 4 ] ] }, "simulation_period": {}, "historical_period": {} } Sequential timesteps ~~~~~~~~~~~~~~~~~~~~ The use of attribute **timesteps_per_week** is shown below. The number 56 following the attribute is the number of timesteps per week. The timesteps is always sequential and is calculated by taking the number of hours in the week = 168 and dividing it by 56 giving 3 hours per timestep. The number of hours per week / **timesteps_per_week** must give an integer value. .. code-block:: json "global_settings": { "name": "example", "timesteps_per_week": 56 "simulation_period": {}, "historical_period": {} }, Output ------ Output will be written to the PRISAVSNITT.DATA file. The first example using the attribute "intraweek_timesteps" will create the file shown below: .. code-block:: 1, * Versjonsnummer paa fil 56, * Antall prisavsnitt 1,'Segment 1 ', * Avsnitt nr, Navn 2,'Segment 2 ', 3,'Segment 3 ', 4,'Segment 4 ', 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 2, 3, 3, 3, 3, 3, 3, 3, 3,Mon, 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 2, 3, 3, 3, 3, 3, 3, 3, 3,Tue, 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 2, 3, 3, 3, 3, 3, 3, 3, 3,Wed, 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 2, 3, 3, 3, 3, 3, 3, 3, 3,Thu, 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 2, 3, 3, 3, 3, 3, 3, 3, 3,Fri, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4,Sat, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4,Sun, The second example using the attribute "timesteps_per_week" will create the file shown below: .. code-block:: 1, * Versjonsnummer paa fil 56, * Antall prisavsnitt 1,'Segment 1 ', * Avsnitt nr, Navn 2,'Segment 2 ', 3,'Segment 3 ', 4,'Segment 4 ', 5,'Segment 5 ', 6,'Segment 6 ', 7,'Segment 7 ', 8,'Segment 8 ', 9,'Segment 9 ', 10,'Segment 10 ', 11,'Segment 11 ', 12,'Segment 12 ', 13,'Segment 13 ', 14,'Segment 14 ', 15,'Segment 15 ', 16,'Segment 16 ', 17,'Segment 17 ', 18,'Segment 18 ', 19,'Segment 19 ', 20,'Segment 20 ', 21,'Segment 21 ', 22,'Segment 22 ', 23,'Segment 23 ', 24,'Segment 24 ', 25,'Segment 25 ', 26,'Segment 26 ', 27,'Segment 27 ', 28,'Segment 28 ', 29,'Segment 29 ', 30,'Segment 30 ', 31,'Segment 31 ', 32,'Segment 32 ', 33,'Segment 33 ', 34,'Segment 34 ', 35,'Segment 35 ', 36,'Segment 36 ', 37,'Segment 37 ', 38,'Segment 38 ', 39,'Segment 39 ', 40,'Segment 40 ', 41,'Segment 41 ', 42,'Segment 42 ', 43,'Segment 43 ', 44,'Segment 44 ', 45,'Segment 45 ', 46,'Segment 46 ', 47,'Segment 47 ', 48,'Segment 48 ', 49,'Segment 49 ', 50,'Segment 50 ', 51,'Segment 51 ', 52,'Segment 52 ', 53,'Segment 53 ', 54,'Segment 54 ', 55,'Segment 55 ', 56,'Segment 56 ', 1, 1, 1, 2, 2, 2, 3, 3, 3, 4, 4, 4, 5, 5, 5, 6, 6, 6, 7, 7, 7, 8, 8, 8,Mon, 9, 9, 9, 10, 10, 10, 11, 11, 11, 12, 12, 12, 13, 13, 13, 14, 14, 14, 15, 15, 15, 16, 16, 16,Tue, 17, 17, 17, 18, 18, 18, 19, 19, 19, 20, 20, 20, 21, 21, 21, 22, 22, 22, 23, 23, 23, 24, 24, 24,Wed, 25, 25, 25, 26, 26, 26, 27, 27, 27, 28, 28, 28, 29, 29, 29, 30, 30, 30, 31, 31, 31, 32, 32, 32,Thu, 33, 33, 33, 34, 34, 34, 35, 35, 35, 36, 36, 36, 37, 37, 37, 38, 38, 38, 39, 39, 39, 40, 40, 40,Fri, 41, 41, 41, 42, 42, 42, 43, 43, 43, 44, 44, 44, 45, 45, 45, 46, 46, 46, 47, 47, 47, 48, 48, 48,Sat, 49, 49, 49, 50, 50, 50, 51, 51, 51, 52, 52, 52, 53, 53, 53, 54, 54, 54, 55, 55, 55, 56, 56, 56,Sun,