Pumps in the LtmApi

The modelling of pumps in the LtmApi is defined by the Pump object.

Pumps example

This example shows how to use pumps in a simulation. A sketch of the system is shown below. The simulation period is from week 20 in 2023 to week 1 2026 and the historical period is 8 years from 2000 - 2007.

The system contains two areas, TEV and pumpekraft. The interconnection between them has a capacity of 200 MW in both directions. The hydropower is located in the pumpekraft area. It contains two pumps, one pump and one pumped power plant, four reservoirs and one hydropower plants.

Pump pump1_upper pumps from rsv_pump_1 to upper_main. The pumps average power is 150 MW.

The pumped hydropower plant extra_plant is a hybrid hydropower plant and a pump. It can reverse the turbines to pump water from lower_main to extra_rsv. The average power is 150 MW at mean pumping head. The pump head is in the range [100, 110] m with corresponding pumping discharge [50, 47] m3/s.

Pumping from the lower reservoir is allowed when the reservoir volume is greater than 5 Mm3 and pumping to the upper reservoir is allowed when the reservoir volume is below 450 Mm3. The upper_reservoir_reference_curve is at 450 Mm3 from week 17-40-50 2023 and the lower_reservoir_reference_curve 5 Mm3 from week 17-40-50 2023.

The attribute average_spill_energy_equivalent on the object Reservoir needs to be set with a resonable value to get resonable pumping results. Be sure to compare it to the discharge_energy_equivalent on the object Plant.

pump_capacity:

• x -> [maximum pump head, minimum pump head] (m)

• y -> [pump discharge at highest pumped head, pump discharge at lowest pumped head] (m3/s)

"pumps": [
   {
         "name": "pump1_upper",
         "ownership": 100,
         "average_power": 150,
         "pump_capacity": {
            "x": [
               100,
               110
            ],
            "y": [
               47,
               50
            ]
         },
         "upper_reservoir_reference_curve": {
            "timestamps": [
               "2023-W17",
               "2023-W40",
               "2023-W50"
            ],
            "scenarios": [
               [
                     450,
                     450,
                     450
               ]
            ]
         },
         "lower_reservoir_reference_curve": {
            "timestamps": [
               "2023-W17",
               "2023-W40",
               "2023-W50"
            ],
            "scenarios": [
               [
                     5,
                     5,
                     5
               ]
            ]
         },
         "unavailable_capacity": {
            "timestamps": [
               "2023-01-02T00:00:00Z",
               "2023-04-02T00:00:00Z",
               "2024-12-01T00:00:00Z"
            ],
            "scenarios": [
               [
                     0,
                     130,
                     130
               ]
            ]
         }
   },
   {
         "name": "extra_pump",
         "ownership": 100,
         "average_power": 150,
         "pump_capacity": {
            "x": [
               100,
               110
            ],
            "y": [
               47,
               50
            ]
         },
         "upper_reservoir_reference_curve": {
            "timestamps": [
               "2023-W17",
               "2023-W40",
               "2023-W50"
            ],
            "scenarios": [
               [
                     1450,
                     1400,
                     1000
               ]
            ]
         },
         "lower_reservoir_reference_curve": {
            "timestamps": [
               "2023-W17",
               "2023-W40",
               "2023-W50"
            ],
            "scenarios": [
               [
                     5,
                     5,
                     5
               ]
            ]
         },
         "unavailable_capacity_": {
            "timestamps": [
               "2023-01-02T00:00:00Z",
               "2023-04-02T00:00:00Z",
               "2023-06-02T00:00:00Z",
               "2024-06-01T00:00:00Z",
               "2024-12-01T00:00:00Z"
            ],
            "scenarios": [
               [
                     0,
                     25,
                     0,
                     50,
                     75
               ]
            ]
         }
   }
],

The link below takes you to a (static) notebook where LTM-API have been run with a simple topology with pumps.

• Pumps

• pumps.json.

Expand to see full JSON listings.

{
    "$schema": "https://gitlab.sintef.no/energy/ltm/pyltmapi/-/raw/main/model.schema.json",
    "model": {
        "global_settings": {
            "name": "global_settings",
            "output_path": "testout_pumps/",
            "default_spill_cost": 0.01,
            "delete_output_dir": false,
            "default_load_penalty": 900.0,
            "generate_output_dir": true,
            "allow_validation_failures": false,
            "interest_rate": 4.42,
            "simulation_period": {
                "timestamps": [
                    "2023-W20",
                    "2026-W01"
                ]
            },
            "historical_type": "civillian",
            "historical_period": {
                "timestamps": [
                    "2000-01-01T00:00:00Z",
                    "2008-01-01T00:00:00Z"
                ]
            },
            "timesteps_per_week": 168
        },
        "dclines": [
            {
                "#comment": "",
                "name": "PUMPE_TEV_DC",
                "forward_capacity": {
                    "scenarios": [
                        [
                            200
                        ]
                    ]
                },
                "backward_capacity": {
                    "timestamps": [
                        "2023-01-02T00:00:00Z",
                        "2023-02-02T00:00:00Z",
                        "2023-03-02T00:00:00Z",
                        "2023-04-02T00:00:00Z",
                        "2023-05-02T00:00:00Z",
                        "2023-06-02T00:00:00Z",
                        "2023-07-02T00:00:00Z",
                        "2023-08-02T00:00:00Z",
                        "2023-09-02T00:00:00Z",
                        "2023-10-02T00:00:00Z",
                        "2023-11-02T00:00:00Z"
                    ],
                    "scenarios": [
                        [
                            100.0,
                            110.0,
                            120.0,
                            130.0,
                            140.0,
                            150.0,
                            160.0,
                            170.0,
                            180.0,
                            190.0,
                            200.0
                        ]
                    ]
                },
                "loss_percentage": 2.0,
                "forward_cost": 2.0,
                "backward_cost": 1.0
            }
        ],
        "market_steps": [
            {
                "name": "market_step",
                "price": {
                    "timestamps": [
                        "2023-01-01T00:00:00Z",
                        "2024-01-01T00:00:00Z"
                    ],
                    "scenarios": [
                        [
                            260,
                            200
                        ]
                    ]
                },
                "capacity": {
                    "timestamps": [
                        "2023-01-01T00:00:00Z"
                    ],
                    "scenarios": [
                        [
                            150
                        ]
                    ]
                }
            }
        ],
        "loads": [
            {
                "#comment": "Gruppe 16",
                "name": "FLAT",
                "capacity": {
                    "timestamps": [
                        "2023-01-01T00:00:00Z"
                    ],
                    "scenarios": [
                        [
                            100
                        ]
                    ]
                }
            },
            {
                "#comment": "Gruppe 16",
                "name": "FLAT2",
                "capacity": {
                    "timestamps": [
                        "2023-01-01T00:00:00Z"
                    ],
                    "scenarios": [
                        [
                            150
                        ]
                    ]
                }
            }
        ],
        "busbars": [
            {
                "name": "pumpekraft"
            },
            {
                "name": "tev"
            }
        ],
        "market_calibration_areas": [
            {
                "name": "calibration_area"
            }
        ],
        "price_series": [],
        "inflow_series": [
            {
                "name": "small",
                "series": {
                    "timestamps": [
                        "1900-01-01T00:00:00Z"
                    ],
                    "scenarios": [
                        [
                            0.001
                        ]
                    ]
                }
            },
            {
                "name": "ten",
                "series": {
                    "timestamps": [
                        "1900-01-01T00:00:00Z"
                    ],
                    "scenarios": [
                        [
                            10.0
                        ]
                    ]
                }
            },
            {
                "name": "after_one_year",
                "series": {
                    "external_reference": {
                        "type": "hdf5",
                        "path": "/inflow/tannsvatn",
                        "filename": "inflow.h5"
                    }
                },
                "forecast": {
                    "external_reference": {
                        "type": "hdf5",
                        "path": "/inflow/tannsvatn",
                        "filename": "inflow.h5"
                    }
                },
                "forecast_period": {
                    "timestamps": [
                        "2023-W25",
                        "2024-W45"
                    ],
                    "scenarios": [
                        [
                            1,
                            0
                        ]
                    ]
                }
            },
            {
                "name": "aamot",
                "series": {
                    "external_reference": {
                        "type": "hdf5",
                        "path": "/inflow/aamot",
                        "filename": "inflow.h5"
                    }
                },
                "forecast": {
                    "timestamps": [
                        "1931-W01"
                    ],
                    "scenarios": [
                        [
                            500
                        ]
                    ]
                }
            },
            {
                "name": "aamot2",
                "series": {
                    "external_reference": {
                        "type": "hdf5",
                        "path": "/inflow/aamot",
                        "filename": "inflow.h5"
                    }
                }
            },
            {
                "name": "dyrdalsvatn",
                "series": {
                    "external_reference": {
                        "type": "hdf5",
                        "path": "/inflow/dyrdalsvatn",
                        "filename": "inflow.h5"
                    }
                }
            },
            {
                "name": "krinsvatn",
                "series": {
                    "external_reference": {
                        "type": "hdf5",
                        "path": "/inflow/krinsvatn",
                        "filename": "inflow.h5"
                    }
                }
            },
            {
                "name": "tannsvatn",
                "series": {
                    "external_reference": {
                        "type": "hdf5",
                        "path": "/inflow/tannsvatn",
                        "filename": "inflow.h5"
                    }
                },
                "forecast": {
                    "timestamps": [
                        "1931-W01"
                    ],
                    "scenarios": [
                        [
                            10000
                        ]
                    ]
                },
                "forecast_period": {
                    "timestamps": [
                        "2023-W20",
                        "2023-W30"
                    ],
                    "scenarios": [
                        [
                            1,
                            0
                        ]
                    ]
                }
            }
        ],
        "reservoirs": [
            {
                "name": "upper_main",
                "average_spill_energy_equivalent": 2.79,
                "degree_of_regulation": 3,
                "regulated_inflow_name": "ten",
                "average_regulated_inflow": 0,
                "max_discharge": 70.30,
                "reference_curve": {
                    "timestamps": [
                        "2023-W17",
                        "2023-W40",
                        "2023-W50"
                    ],
                    "scenarios": [
                        [
                            200,
                            450,
                            350
                        ]
                    ]
                },
                "initial_volume": 400,
                "volume_curve": {
                    "x": [
                        1125.20,
                        1129.20
                    ],
                    "y": [
                        0,
                        500
                    ]
                }
            },
            {
                "name": "extra_rsv",
                "average_spill_energy_equivalent": 0.8,
                "degree_of_regulation": 1,
                "regulated_inflow_name": "ten",
                "average_regulated_inflow": 1.0,
                "max_discharge": 170.30,
                "reference_curve": {
                    "timestamps": [
                        "2023-W01"
                    ],
                    "scenarios": [
                        [
                            500
                        ]
                    ]
                },
                "initial_volume": 750,
                "volume_curve": {
                    "x": [
                        600,
                        630
                    ],
                    "y": [
                        0,
                        1500
                    ]
                }
            },
            {
                "name": "lower_main",
                "average_spill_energy_equivalent": 1.0,
                "degree_of_regulation": 1,
                "regulated_inflow_name": "ten",
                "average_regulated_inflow": 0.0,
                "max_discharge": 100.0,
                "reference_curve": {
                    "timestamps": [
                        "2023-W01"
                    ],
                    "scenarios": [
                        [
                            30.0
                        ]
                    ]
                },
                "initial_volume": 1,
                "volume_curve": {
                    "x": [
                        45,
                        50
                    ],
                    "y": [
                        0,
                        45
                    ]
                },
                "tailrace_elevation": 40.0,
                "gross_head": 3
            },
            {
                "name": "rsv_pump_1",
                "average_spill_energy_equivalent": 1.0,
                "degree_of_regulation": 3,
                "regulated_inflow_name": "after_one_year",
                "average_regulated_inflow": 20,
                "max_discharge": 45,
                "reference_curve": {
                    "timestamps": [
                        "2023-W01"
                    ],
                    "scenarios": [
                        [
                            30.0
                        ]
                    ]
                },
                "initial_volume": 200,
                "volume_curve": {
                    "x": [
                        1000,
                        1050
                    ],
                    "y": [
                        0,
                        250
                    ]
                },
                "tailrace_elevation": 1000.0,
                "gross_head": 50
            }
        ],
        "plants": [
            {
                "name": "plant",
                "ownership": 100,
                "discharge_energy_equivalent": {
                    "timestamps": [
                        "2023-W01"
                    ],
                    "scenarios": [
                        [
                            2.7900
                        ]
                    ]
                },
                "pq_curves": {
                    "2023-01-02T00:00:00Z": {
                        "x": [
                            0.0,
                            70.30
                        ],
                        "y": [
                            0.0,
                            200.0
                        ]
                    }
                },
                "unregulated_inflow_name": "small",
                "average_unregulated_inflow": 0.0,
                "tailrace_elevation": 50.0,
                "gross_head": 900.0,
                "unavailable_capacity": {
                    "timestamps": [
                        "2023-01-02T00:00:00Z",
                        "2024-06-01T00:00:00Z",
                        "2024-12-01T00:00:00Z"
                    ],
                    "scenarios": [
                        [
                            170,
                            150,
                            0
                        ]
                    ]
                }
            },
            {
                "name": "extra_plant",
                "ownership": 100,
                "discharge_energy_equivalent": {
                    "timestamps": [
                        "W01"
                    ],
                    "scenarios": [
                        [
                            0.7900
                        ]
                    ]
                },
                "pq_curves": {
                    "W01": {
                        "x": [
                            0.0,
                            100.0
                        ],
                        "y": [
                            0.0,
                            100.0
                        ]
                    },
                    "W20": {
                        "x": [
                            0.0,
                            170.0
                        ],
                        "y": [
                            0.0,
                            150.0
                        ]
                    },
                    "W40": {
                        "x": [
                            0.0,
                            90.30
                        ],
                        "y": [
                            0.0,
                            90.0
                        ]
                    }
                },
                "unregulated_inflow_name": "small",
                "average_unregulated_inflow": 0.0,
                "tailrace_elevation": 150.0,
                "gross_head": 450.0,
                "unavailable_capacity": {
                    "timestamps": [
                        "2023-01-02T00:00:00Z",
                        "2023-02-02T00:00:00Z",
                        "2024-06-01T00:00:00Z",
                        "2024-12-01T00:00:00Z"
                    ],
                    "scenarios": [
                        [
                            130,
                            100,
                            50,
                            0
                        ]
                    ]
                }
            }
        ],
        "pumps": [
            {
                "name": "pump1_upper",
                "ownership": 100,
                "average_power": 150,
                "pump_capacity": {
                    "x": [
                        110,
                        100
                    ],
                    "y": [
                        47,
                        150
                    ]
                },
                "upper_reservoir_reference_curve": {
                    "name": "pump1_upper_high_refcurve",
                    "timestamps": [
                        "2023-W20",
                        "2023-W40",
                        "2023-W50"
                    ],
                    "scenarios": [
                        [
                            200,
                            200,
                            200
                        ]
                    ]
                },
                "lower_reservoir_reference_curve": {
                    "name": "pump1_upper_low_refcurve",
                    "timestamps": [
                        "2023-W20",
                        "2023-W40",
                        "2023-W50"
                    ],
                    "scenarios": [
                        [
                            5,
                            5,
                            5
                        ]
                    ]
                },
                "unavailable_capacity": {
                    "timestamps": [
                        "2023-01-02T00:00:00Z",
                        "2023-04-02T00:00:00Z",
                        "2024-12-01T00:00:00Z"
                    ],
                    "scenarios": [
                        [
                            0,
                            130,
                            130
                        ]
                    ]
                }
            },
            {
                "name": "extra_pump_æøå",
                "ownership": 100,
                "average_power": 150,
                "pump_capacity": {
                    "x": [
                        110,
                        100
                    ],
                    "y": [
                        47,
                        150
                    ]
                },
                "upper_reservoir_reference_curve": {
                    "timestamps": [
                        "2023-W17",
                        "2023-W40",
                        "2023-W50"
                    ],
                    "scenarios": [
                        [
                            1450,
                            1400,
                            1000
                        ]
                    ]
                },
                "lower_reservoir_reference_curve": {
                    "timestamps": [
                        "2023-W17",
                        "2023-W40",
                        "2023-W50"
                    ],
                    "scenarios": [
                        [
                            5,
                            5,
                            5
                        ]
                    ]
                },
                "unavailable_capacity_": {
                    "timestamps": [
                        "2023-01-02T00:00:00Z",
                        "2023-04-02T00:00:00Z",
                        "2023-06-02T00:00:00Z",
                        "2024-06-01T00:00:00Z",
                        "2024-12-01T00:00:00Z"
                    ],
                    "scenarios": [
                        [
                            0,
                            25,
                            0,
                            50,
                            75
                        ]
                    ]
                }
            }
        ],
        "wind": [
            {
                "name": "WIND_TEST_01",
                "capacity": {
                    "timestamps": [
                        "1981-01-01T00:00:00Z",
                        "1981-01-03T00:00:00Z"
                    ],
                    "scenarios": [
                        [
                            0.1,
                            0.1
                        ],
                        [
                            0.2,
                            0.2
                        ],
                        [
                            0.3,
                            0.3
                        ],
                        [
                            0.4,
                            0.4
                        ],
                        [
                            0.5,
                            0.5
                        ],
                        [
                            0.6,
                            0.6
                        ],
                        [
                            0.7,
                            0.7
                        ],
                        [
                            0.8,
                            0.8
                        ]
                    ]
                }
            }
        ],
        "connections": [
            {
                "from": "WIND_TEST_01",
                "to": "tev"
            },
            {
                "from": "pumpekraft",
                "to": "PUMPE_TEV_DC"
            },
            {
                "from": "market_step",
                "to": "pumpekraft"
            },
            {
                "from": "PUMPE_TEV_DC",
                "to": "tev"
            },
            {
                "from": "FLAT",
                "to": "pumpekraft"
            },
            {
                "from": "FLAT2",
                "to": "tev"
            },
            {
                "from": "upper_main",
                "to": "pumpekraft"
            },
            {
                "from": "upper_main",
                "to": "plant"
            },
            {
                "from": "plant",
                "to": "lower_main"
            },
            {
                "from": "rsv_pump_1",
                "to": "pumpekraft"
            },
            {
                "from": "rsv_pump_1",
                "to": "pump1_upper"
            },
            {
                "from": "pump1_upper",
                "to": "upper_main"
            },
            {
                "from": "extra_rsv",
                "to": "extra_plant"
            },
            {
                "from": "extra_plant",
                "to": "lower_main"
            },
            {
                "from": "extra_pump_æøå",
                "to": "extra_plant"
            },
            {
                "from": "pumpekraft",
                "to": "calibration_area"
            },
            {
                "from": "tev",
                "to": "calibration_area"
            }
        ]
    }
}