GitHub

Migrating from version 3.0 to 4.0

This guide outlines the code updates required to upgrade from PowerSystems.jl version 3.0 to 4.0, which was released in June 2024 and includes breaking changes. These are:

Renamed Types and Parameters

Some Types and fields were renamed, which should require a trivial search and replace:

Renamed Types:

Renamed parameters:

New and Eliminated Types

In addition to cost-related types detailed in New Cost Functions, these new types have been added:

These types are no longer part of PowerSystems.jl, although there are future plans to rework some of them:

Updates to Energy Storage Parameters

EnergyReservoirStorage is now the default battery and energy storage model, replacing GenericBattery.

There are also changes to the data fields compared to GenericBattery to improve clarity and modeling flexibility.

New data fields:

  • storage_capacity for the maximum storage capacity (can be in units of, e.g., MWh for batteries or liters for hydrogen)

    • Example: 10000.0 for 10,000 liters hydrogen

  • storage_level_limits for the minimum and maximum allowable storage levels on [0, 1], which can be used to model derates or other restrictions, such as state-of-charge restrictions on battery cycling

    • Example: Minimum of 0.2 and maximum of 1.0 to restrict the storage from dropping below 20% capacity to keep some reserve margin available at all times

  • initial_storage_capacity_level for the initial storage capacity level as a ratio [0, 1.0] of storage_capacity

    • Example: 0.5 to start the storage at 50% full

  • conversion_factor is the (optional) conversion factor of storage_capacity to MWh, if different than 1.0 (i.e., no conversion is needed if the storage_capacity is in MWh)

    • Example: 0.0005 for 0.5 kWh/l hydrogen

Removed data fields:

  • state_of_charge_limits with units of p.u.-hr
  • initial_energy with units of p.u.-hr

Hydropower status added

A new required parameter, status, was added to HydroEnergyReservoir and HydroPumpedStorage, for the initial condition of the generator.

New Cost Functions

New Time Series Horizon Format

The horizon for a forecast has changed from a count of time steps (as an Int) to a duration, as a Dates.Period

Example day-ahead forecast: A forecast with hourly resolution for the next 24 hours, with a new forecast available every 24 hours (i.e., 24-hour interval)

  • The horizon is now Dates.Hour(24) or Dates.Day(1)
  • Previously in version 3.0, the horizon would have been 24 for the 24 1-hour time-steps in each forecast

Example hour-ahead forecast: A forecast with 5-minute resolution for the next 1 hour, with a new forecast available every hour (i.e., 1-hour interval)

  • The horizon is now Dates.Hour(1)
  • Previously in version 3.0, the horizon would have been 12 for the 12 5-minute time-steps in each forecast

Minor Type Hierarchy Change

The vast majority of users are not expected to be impacted by this change.

(Temporary) Use Version 3.0 for HybridSystem (+ new parameter)

The HybridSystem is currently not supported in the rest of the Sienna ecosystem, such as PowerSimulations.jl. To use HybridSystem in simulation, revert to version 3.0. There are plans to update HybridSystem for version 4.0, but they have not been completed.

In addition, HybridSystem has a new required parameter: interconnection_efficiency