9.3 Modifying a Case

9.3.1 extract_islands

  mpc_array = extract_islands(mpc)
  mpc_array = extract_islands(mpc, groups)
  mpc_k = extract_islands(mpc, k)
  mpc_k = extract_islands(mpc, groups, k)
  mpc_k = extract_islands(mpc, k, custom)
  mpc_k = extract_islands(mpc, groups, k, custom)

The extract_islands function extracts individual islands in a network that is not fully connected. The original network is specified as a Matpower case struct (mpc) and the result is returned as a cell array of case structs, or as a single case struct. Supplying the optional group avoids the need to traverse the network again, saving time on large systems. A final optional argument custom is a struct that can be used to indicate custom fields of mpc from which to extract data corresponding to buses generators, branches or DC lines.

9.3.2 load2disp

  mpc = load2disp(mpc0)
  mpc = load2disp(mpc0, fname)
  mpc = load2disp(mpc0, fname, idx)
  mpc = load2disp(mpc0, fname, idx, voll)

The load2disp function takes a Matpower case mpc0, converts fixed loads to dispatchable loads, curtailable at a specific price, and returns the resulting case struct mpc. It can optionally save the resulting case to a file (fname), convert loads only at specific buses (idx), and set the value of lost load (voll) to be used as the curtailment price (default is $5,000/MWh).

9.3.3 modcost

  newgencost = modcost(gencost, alpha)
  newgencost = modcost(gencost, alpha, modtype)

The modcost function can be used to modify generator cost functions by shifting or scaling them, either horizontally or vertically. The alpha argument specifies the numerical value of the modification, and modtype defines the type of modification as a string that takes one of the following values: 'SCALE_F' (default), 'SCALE_X', 'SHIFT_F', or 'SHIFT_X'.

9.3.4 scale_load

  mpc = scale_load(load, mpc)
  mpc = scale_load(load, mpc, load_zone)
  mpc = scale_load(load, mpc, load_zone, opt)
  bus = scale_load(load, bus)
  [bus, gen] = scale_load(load, bus, gen, load_zone, opt)
  [bus, gen, gencost] = ...
      scale_load(load, bus, gen, load_zone, opt, gencost)

The scale_load function is used to scale active (and optionally reactive) loads in each zone by a zone-specific ratio, i.e. R(k)  for zone k  . The amount of scaling for each zone, either as a direct scale factor or as a target quantity, is specified in load. The load zones are defined by load_zone, and opt specifies the type of scaling (factor or target quantity) and which loads are affected (active, reactive or both and fixed, dispatchable or both). The costs (gencost) associated with dispatchable loads can also be optionally scaled with the loads.

9.3.5 apply_changes

  mpc_modified = apply_changes(label, mpc_original, chgtab)

The apply_changes function implements a general mechanism to apply a set of changes to a base Matpower case. This can be used, for example, to define and apply a set of contingencies. There are three basic types of changes, those that replace old values with new ones, those that scale old values by some factor, and those that add a constant to existing values.

The change table matrix, chgtab, specifies modifications to be applied to an existing case. These modifications are grouped into sets, designated change sets, that are always applied as a group. A change set consists of one or more changes, each specified in a separate row in the chgtab, where the rows share a common label (integer ID).

For example, nc  change sets can be used to define nc  contingencies via a single chgtab with many rows, but only nc  unique labels. The chgtab also optionally specifies a probability π
  k  of occurance associated with change set k  . Table 9-1 summarizes the meaning of the data in each column of chgtab. All of the names referenced in Tables 9-1 through 9-4 are defined as constants by the idx_ct function. Type help idx_ct at the Matlab prompt for more details. Use of the named constants when constructing a chgtab matrix is encouraged to improve readability.

Table 9-1:Columns of chgtab
name column description
CT_LABEL 1 change set label, unique for each change set (integer)
CT_PROB 2 change set probability (number between 0 and 1)
CT_TABLE 3 type of table to be modified (see Table 9-2 for possible values)
CT_ROW 4 row index of data to be modified, 0 means all rows,
for area-wide changes this is the area index, rather than row index
CT_COL 5 column index of data to be modified (see Table 9-4 for exceptions)
CT_CHGTYPE 6 type of change, e.g. replace, scale or add (see Table 9-3 for details)
CT_NEWVAL 7 new value used to replace or modify existing data

The change set probability πk  is taken from this column of the first row for change set k  .

The value in the CT_TABLE column of chgtab defines which data table is to be modified and the options are given in Table 9-2. With the exception of load and certain generator cost changes, each individual change record specifies modification(s) to a single column of a particular data matrix, either bus, gen, branch or gencost. Some are changes to that column for an individual row in the matrix (or all rows, if the row index is set to 0), while others are area-wide changes that modify all rows corresponding to the specified area.55

Load changes are special and may modify multiple columns of the bus and/or gen tables. They offer a more flexible and convenient means of specifying modifications to loads (fixed, dispatchable, real and/or reactive) than directly including individual change specifications for each of the corresponding entries in the bus and gen matrices. The row indices for load changes refer to bus numbers.

In addition to the normal direct modifications for generator cost parameters, there is also the option to scale or shift an entire cost function, either vertically or horizontally. This is often more convenient than manipulating the individual cost parameters directly, especially when dealing with a mix of polynomial and piecewise linear generator costs.

Table 9-2:Values for CT_TABLE Column
name value description
CT_TBUS 1 bus table
CT_TGEN 2 gen table
CT_TBRCH 3 branch table
CT_TAREABUS 4 area-wide change in bus table
CT_TAREAGEN 5 area-wide change in gen table
CT_TAREABRCH 6 area-wide change in branch table
CT_TLOAD 7 per bus load change
CT_TAREALOAD 8 area-wide load change
CT_TGENCOST 9 gencost table
CT_TAREAGENCOST 10 area-wide change in gencost table

Preferred method of modifying load, as opposed to manipulating bus and gen tables directly.

Normally, the CT_COL column contains the column index of the entry or entries in the data tables to be modified. And the CT_CHGTYPE and CT_NEWVAL columns specify, respectively, the type of change (replacement, scaling or adding) and the corresponding replacement value, scale factor or constant to add, as shown in Table 9-3.

Table 9-3:Values for CT_CHGTYPE Column
name value description
CT_REP 1 replace old value by new one in CT_NEWVAL column
CT_REL 2 scale old value by factor in CT_NEWVAL column
CT_ADD 3 add value in CT_NEWVAL column to old value

For load changes, the CT_COL column is not a column index, but rather a code that defines which loads at the specified bus(es) are to be modified, with the ability to select fixed loads only, dispatchable loads only or both, and for each whether or not to include the reactive load in the change. Similarly, the CT_COL column for generator cost modifications can be set to a special code to indicate a scaling or shifting of the entire corresponding cost function(s). The various options for the CT_COL column are summarized in Table 9-4.

Table 9-4:Values for CT_COL Column
name value description
CT_LOAD_ALL_PQ 1 modify all (fixed & dispatchable) loads, active and reactive
CT_LOAD_FIX_PQ 2 modify fixed loads, active and reactive
CT_LOAD_DIS_PQ 3 modify dispatchable loads, active and reactive
CT_LOAD_ALL_P 4 modify all (fixed & dispatchable) loads, active power only
CT_LOAD_FIX_P 5 modify fixed loads, active power only
CT_LOAD_DIS_P 6 modify dispatchable loads, active power only
CT_MODCOST_F -1 scales or shifts the cost function vertically
CT_MODCOST_X -2 scales or shifts the cost function horizontally
n  index of column in data matrix to be modified

Use CT_CHGTYPE column = CT_REL to scale the cost and CT_ADD to shift the cost. Can also be used for CT_TGENCOST or CT_TAREAGENCOST in addition to the special codes above.

For example, setting up a chgtab matrix for the following four scenarios could be done as shown below.

Turn off generator 2 (10% probability).
Reduce the line rating of all lines to 95% of their nominal values (0.2% probability).
Scale all loads in area 2 (real & reactive, fixed & dispatchable) up by 10% (0.1% probability).
Decrease capacity of generator 3 and shift its cost function to the left both by 10 MW (5% probability).
chgtab = [ ...
1   0.1   CT_TGEN       2  GEN_STATUS     CT_REP    0;
2   0.002 CT_TBRCH      0  RATE_A         CT_REL    0.95;
3   0.001 CT_TAREALOAD  2  CT_LOAD_ALL_PQ CT_REL    1.1;
4   0.05  CT_TGEN       3  PMAX           CT_ADD  -10;
4   0.05  CT_TGENCOST   3  CT_MODCOST_X   CT_ADD  -10;

A change table can be used to easily create modified cases from an existing base case with the apply_changes function. Given the chgtab from the example above, a new case with all lines derated by 5% can easily be created from an existing case mpc with the following line of code.

mpc_new = apply_changes(2, mpc, chgtab);
9.3.6 savechgtab

  savechgtab(fname, chgtab)
  savechgtab(fname, chgtab, warnings)
  fname = savechgtab(fname, ...)

This function can be used to save a change table matrix, chgtab, to a file specified by fname. If the fname string ends with '.mat' it saves chgtab and warnings to a MAT-file as the variables chgtab and warnings, respectively. Otherwise, it saves an M-file function that returns the chgtab, with the optional warnings included in the comments, where warnings is a cell array of warning messages such as those returned by pssecon2chgtab.