GitHub

Model customization

In the previous tutorial, we used UnitCommitment.jl to solve benchmark and user-provided instances using a default mathematical formulation for the problem. In this tutorial, we will explore how to customize this formulation.

Warning

This tutorial is not required for using UnitCommitment.jl, unless you plan to make changes to the problem formulation. In this page, we assume familiarity with the JuMP modeling language. Please see JuMP's official documentation for resources on getting started with JuMP.

Selecting modeling components

By default, UnitCommitment.build_model uses a formulation that combines modeling components from different publications, and that has been carefully tested, using our own benchmark scripts, to provide good performance across a wide variety of instances. This default formulation is expected to change over time, as new methods are proposed in the literature. You can, however, construct your own formulation, based on the modeling components that you choose, as shown in the next example.

We start by importing the necessary packages and reading a benchmark instance:

using HiGHS
using JuMP
using UnitCommitment

instance = UnitCommitment.read_benchmark("matpower/case14/2017-01-01");

Next, instead of calling UnitCommitment.build_model with default arguments, we can provide a UnitCommitment.Formulation object, which describes what modeling components to use, and how should they be configured. For a complete list of modeling components available in UnitCommitment.jl, see the API docs.

In the example below, we switch to piecewise-linear cost modeling as defined in KnuOstWat2018, as well as ramping and startup costs formulation as defined in MorLatRam2013. In addition, we specify custom cutoffs for the shift factors formulation.

model = UnitCommitment.build_model(
    instance = instance,
    optimizer = HiGHS.Optimizer,
    formulation = UnitCommitment.Formulation(
        pwl_costs = UnitCommitment.KnuOstWat2018.PwlCosts(),
        ramping = UnitCommitment.MorLatRam2013.Ramping(),
        startup_costs = UnitCommitment.MorLatRam2013.StartupCosts(),
        transmission = UnitCommitment.ShiftFactorsFormulation(
            isf_cutoff = 0.008,
            lodf_cutoff = 0.003,
        ),
    ),
);
[ Info: Building model...
[ Info: Building scenario s1 with probability 1.0
[ Info: Computing injection shift factors...
[ Info: Computed ISF in 0.00 seconds
[ Info: Computing line outage factors...
[ Info: Computed LODF in 0.00 seconds
[ Info: Applying PTDF and LODF cutoffs (0.00800, 0.00300)
[ Info: Built model in 0.89 seconds

Accessing decision variables

In the previous tutorial, we saw how to access the optimal solution through UnitCommitment.solution. While this approach works well for basic usage, it is also possible to get a direct reference to the JuMP decision variables and query their values, as the next example illustrates.

First, we load a benchmark instance and solve it, as before.

instance = UnitCommitment.read_benchmark("matpower/case14/2017-01-01");
model =
    UnitCommitment.build_model(instance = instance, optimizer = HiGHS.Optimizer);
UnitCommitment.optimize!(model)
[ Info: Building model...
[ Info: Building scenario s1 with probability 1.0
[ Info: Computing injection shift factors...
[ Info: Computed ISF in 0.00 seconds
[ Info: Computing line outage factors...
[ Info: Computed LODF in 0.00 seconds
[ Info: Applying PTDF and LODF cutoffs (0.00500, 0.00100)
[ Info: Built model in 0.01 seconds
[ Info: Setting MILP time limit to 86399.99 seconds
[ Info: Solving MILP...
Running HiGHS 1.6.0: Copyright (c) 2023 HiGHS under MIT licence terms
Presolving model
4382 rows, 2704 cols, 14776 nonzeros
3279 rows, 2195 cols, 11913 nonzeros
3160 rows, 2085 cols, 12983 nonzeros

Solving MIP model with:
   3160 rows
   2085 cols (865 binary, 0 integer, 0 implied int., 1220 continuous)
   12983 nonzeros

        Nodes      |    B&B Tree     |            Objective Bounds              |  Dynamic Constraints |       Work
     Proc. InQueue |  Leaves   Expl. | BestBound       BestSol              Gap |   Cuts   InLp Confl. | LpIters     Time

         0       0         0   0.00%   1.86264515e-09  inf                  inf        0      0      0         0     0.0s
 R       0       0         0   0.00%   360642.328869   360642.544974      0.00%        0      0      0       861     0.1s

Solving report
  Status            Optimal
  Primal bound      360642.544974
  Dual bound        360642.328869
  Gap               6e-05% (tolerance: 0.01%)
  Solution status   feasible
                    360642.544974 (objective)
                    0 (bound viol.)
                    0 (int. viol.)
                    0 (row viol.)
  Timing            0.06 (total)
                    0.03 (presolve)
                    0.00 (postsolve)
  Nodes             1
  LP iterations     861 (total)
                    0 (strong br.)
                    0 (separation)
                    0 (heuristics)
[ Info: Verifying transmission limits...
[ Info: Verified transmission limits in 0.59 seconds
[ Info: No violations found

At this point, it is possible to obtain a reference to the decision variables by calling model[:varname][index]. For example, model[:is_on]["g1",1] returns a direct reference to the JuMP variable indicating whether generator named "g1" is on at time 1. For a complete list of decision variables available, and how are they indexed, see the problem definition.

@show JuMP.value(model[:is_on]["g1", 1])
1.0

To access second-stage decisions, it is necessary to specify the scenario name. UnitCommitment.jl models deterministic instances as a particular case in which there is a single scenario named "s1", so we need to use this key.

@show JuMP.value(model[:prod_above]["s1", "g1", 1])
145.16900936037393

Modifying variables and constraints

When testing variations of the unit commitment problem, it is often necessary to modify the objective function, variables and constraints of the formulation. UnitCommitment.jl makes this process relatively easy. The first step is to construct the standard model using UnitCommitment.build_model:

instance = UnitCommitment.read_benchmark("matpower/case14/2017-01-01");
model =
    UnitCommitment.build_model(instance = instance, optimizer = HiGHS.Optimizer);
[ Info: Building model...
[ Info: Building scenario s1 with probability 1.0
[ Info: Computing injection shift factors...
[ Info: Computed ISF in 0.00 seconds
[ Info: Computing line outage factors...
[ Info: Computed LODF in 0.00 seconds
[ Info: Applying PTDF and LODF cutoffs (0.00500, 0.00100)
[ Info: Built model in 0.01 seconds

Now, before calling UnitCommitment.optimize, we can make any desired changes to the formulation. In the previous section, we saw how to obtain a direct reference to the decision variables. It is possible to modify them by using standard JuMP methods. For example, to fix the commitment status of a particular generator, we can use JuMP.fix:

JuMP.fix(model[:is_on]["g1", 1], 1.0, force = true)

To modify the cost coefficient of a particular variable, we can use JuMP.set_objective_coefficient:

JuMP.set_objective_coefficient(model, model[:switch_on]["g1", 1], 1000.0)

It is also possible to make changes to the set of constraints. For example, we can add a custom constraint, using the JuMP.@constraint macro:

@constraint(model, model[:is_on]["g3", 1] + model[:is_on]["g4", 1] <= 1,);

We can also remove an existing model constraint using JuMP.delete. See the problem definition for a list of constraint names and indices.

JuMP.delete(model, model[:eq_min_uptime]["g1", 1])

After we are done with all changes, we can call UnitCommitment.optimize and extract the optimal solution:

UnitCommitment.optimize!(model)
@show UnitCommitment.solution(model)
OrderedCollections.OrderedDict{Any, Any} with 15 entries:
  "Thermal production (MW)"         => OrderedDict("g1"=>[181.92, 172.85, 166.8…
  "Thermal production cost (\$)"    => OrderedDict("g1"=>[7241.95, 6839.01, 657…
  "Startup cost (\$)"               => OrderedDict("g1"=>[0.0, 0.0, 0.0, 0.0, 0…
  "Is on"                           => OrderedDict("g1"=>[1.0, 1.0, 1.0, 1.0, 1…
  "Switch on"                       => OrderedDict("g1"=>[0.0, 0.0, 0.0, 0.0, 0…
  "Switch off"                      => OrderedDict("g1"=>[0.0, 0.0, 0.0, 0.0, 0…
  "Net injection (MW)"              => OrderedDict("b1"=>[181.92, 172.85, 166.8…
  "Load curtail (MW)"               => OrderedDict("b1"=>[0.0, 0.0, 0.0, 0.0, 0…
  "Line overflow (MW)"              => OrderedDict("l1"=>[0.0, 0.0, 0.0, 0.0, 0…
  "Spinning reserve (MW)"           => OrderedDict("r1"=>OrderedDict("g1"=>[4.6…
  "Spinning reserve shortfall (MW)" => OrderedDict("r1"=>[0.0, 0.0, 0.0, 0.0, 0…
  "Up-flexiramp (MW)"               => OrderedDict{Any, Any}()
  "Up-flexiramp shortfall (MW)"     => OrderedDict{Any, Any}()
  "Down-flexiramp (MW)"             => OrderedDict{Any, Any}()
  "Down-flexiramp shortfall (MW)"   => OrderedDict{Any, Any}()

Modeling new grid components

In this section we demonstrate how to add a new grid component to a particular bus in the network. This is useful, for example, when developing formulations for a new type of generator, energy storage, or any other grid device. We start by reading the instance data and buliding a standard model:

instance = UnitCommitment.read_benchmark("matpower/case118/2017-02-01")
model =
    UnitCommitment.build_model(instance = instance, optimizer = HiGHS.Optimizer);
[ Info: Building model...
[ Info: Building scenario s1 with probability 1.0
[ Info: Computing injection shift factors...
[ Info: Computed ISF in 0.23 seconds
[ Info: Computing line outage factors...
[ Info: Computed LODF in 0.00 seconds
[ Info: Applying PTDF and LODF cutoffs (0.00500, 0.00100)
[ Info: Built model in 0.41 seconds

Next, we create decision variables for the new grid component. In this example, we assume that the new component can inject up to 10 MW of power at each time step, so we create new continuous variables $0 \leq x_t \leq 10$.

T = instance.time
@variable(model, x[1:T], lower_bound = 0.0, upper_bound = 10.0);

Next, we add the production costs to the objective function. In this example, we assume a generation cost of $5/MW:

for t in 1:T
    set_objective_coefficient(model, x[t], 5.0)
end

We then attach the new component to bus b1 by modifying the net injection constraint (eq_net_injection):

for t in 1:T
    set_normalized_coefficient(
        model[:eq_net_injection]["s1", "b1", t],
        x[t],
        1.0,
    )
end

Next, we solve the model:

UnitCommitment.optimize!(model)
[ Info: Setting MILP time limit to 86400.00 seconds
[ Info: Solving MILP...
Running HiGHS 1.6.0: Copyright (c) 2023 HiGHS under MIT licence terms
Presolving model
43013 rows, 28344 cols, 156154 nonzeros
33218 rows, 24204 cols, 127961 nonzeros
31173 rows, 21188 cols, 126079 nonzeros

Solving MIP model with:
   31173 rows
   21188 cols (9100 binary, 0 integer, 0 implied int., 12088 continuous)
   126079 nonzeros

        Nodes      |    B&B Tree     |            Objective Bounds              |  Dynamic Constraints |       Work
     Proc. InQueue |  Leaves   Expl. | BestBound       BestSol              Gap |   Cuts   InLp Confl. | LpIters     Time

         0       0         0   0.00%   -501782.068184  inf                  inf        0      0      0         0     0.5s
 R       0       0         0   0.00%   5748240.007416  5748250.232723     0.00%        0      0      0      8320     1.0s

Solving report
  Status            Optimal
  Primal bound      5748250.23272
  Dual bound        5748240.00742
  Gap               0.000178% (tolerance: 0.01%)
  Solution status   feasible
                    5748250.23272 (objective)
                    0 (bound viol.)
                    2.22044604925e-15 (int. viol.)
                    0 (row viol.)
  Timing            0.97 (total)
                    0.36 (presolve)
                    0.00 (postsolve)
  Nodes             1
  LP iterations     8320 (total)
                    0 (strong br.)
                    0 (separation)
                    0 (heuristics)
[ Info: Verifying transmission limits...
[ Info: Verified transmission limits in 0.01 seconds
[ Info: No violations found

We then finally extract the optimal value of the $x$ variables:

@show value.(x)
36-element Vector{Float64}:
 10.0
 10.0
 10.0
 10.0
 10.0
 10.0
 10.0
 10.0
 10.0
 10.0
  ⋮
 10.0
 10.0
 10.0
 10.0
 10.0
 10.0
 10.0
 10.0
 10.0