runcpf

5.6 runcpf

In Matpower, a continuation power ﬂow is executed by calling runcpf with two Matpower cases (case structs or case ﬁle names) as the ﬁrst two arguments, basecasedata and targetcasedata, respectively. The ﬁrst contains the base loading/generation proﬁle while the second contains the target loading/generation proﬁle. In addition to printing output to the screen, which it does by default, runcpf optionally returns the solution in a results struct.

>> results = runcpf(basecasedata, targetcasedata);

Additional optional input arguments can be used to set options (mpopt) and provide ﬁle names for saving the pretty printed output (fname) or the solved case data (solvedcase).

>> results = runcpf(basecasedata, targetcasedata, mpopt, fname, solvedcase);

The results struct is a superset of the input Matpower case struct mpc, with some additional ﬁelds as well as additional columns in some of the existing data ﬁelds. In addition to the solution values included in the results for a simple power ﬂow, shown in Table 4-1 in Section 4.4, the following additional continuation power ﬂow solution values are stored in the cpf ﬁeld as shown in Table 5-1.

Table 5-1:Continuation Power Flow Results

The options that control the continuation power ﬂow simulation are listed in Table 5-2. All the power ﬂow options for Newton’s method (tolerance, maximum iterations) and for controlling the output on the screen (see Tables 4-2 and 4-3) are also available with the continuation power ﬂow.

λstop — Table 5-2:Continuation Power Flow Options

Table 5-2:Continuation Power Flow Options

5.6.1 CPF Callback Functions

Matpower’s continuation power ﬂow provides a callback mechanism to give the user access to the iteration process for executing custom code at each iteration, for example, to implement custom incremental plotting of a PV nose curve or to handle a detected event. This callback mechanism is used internally to handle default plotting functionality as well as to handle the standard CPF events. The cpf_default_callback function, for example, is used to collect the $λ$ and $V$ results from each predictor and corrector iteration and optionally plot the PV nose curve.

The prototype for a CPF callback function is

function [nx, cx, done, rollback, evnts, cb_data, results] = ...
cpf_user_callback(k, nx, cx, px, done, rollback, evnts, ...
cb_data, cb_args, results)

and the input and output arguments are described in Tables 5-3 through 5-5 and in the help for cpf_default_callback. Each registered CPF callback function is called in three diﬀerent contexts, distinguished by the value of the ﬁrst argument k as follows:

1.: initial – called with k = 0, without results input/output arguments, after base power ﬂow, before ﬁrst CPF step.
2.: iterations – called with k $> 0$ , without results input/output arguments, at each iteration, after predictor-corrector step
3.: ﬁnal – called with k $< 0$ , with results input/output arguments, after exiting predictor-corrector loop, inputs identical to last iteration call, except k negated

Table 5-3:Continuation Power Flow Callback Input Arguments

Table 5-4:Continuation Power Flow Callback Output Arguments

name	description
All are updated versions of the corresponding input arguments, see Table 5-3 for more details.
nx	next CPF state^*,user state (cb ﬁeld) should be updated here if rollback is false
cx	current CPF state^*,may contain updated this_step or this_parm values to be used if rollback is true
done	callback may have requested termination and set the msg ﬁeld
rollback	callback can request a rollback step, even if it was not indicated by an event function^†
evnts	msg ﬁeld for a given event may be updated^‡
cb_data	this data should only be modiﬁed if the underlying problem has been changed (e.g. generator limit reached), in which case it should always be followed by a step of zero length, i.e. set nx.this_step to 0^§
results	updated version of results input argument to be assigned to cpf ﬁeld of results struct returned by runcpf

^* See Table 5-5 for details of the CPF state. ^† In this case, the callback should also modify the step size or parameterization to be used for the re-try, by setting the this_step or this_parm ﬁelds in cx. ^‡ See cpf_detect_events for details of the evnts ﬁeld. ^§ It is the job of any callback modifying cb_data to ensure that all data in cb_data is kept consistent.

The user can deﬁne their own callback functions which take the same form and are called in the same contexts as cpf_default_callback. User callback functions are speciﬁed via the Matpower option cpf.user_callback. This option can be a string containing the name of the callback function, or a struct with the following ﬁelds, where all but the ﬁrst are optional:

fcn - string with name of callback function
priority - numerical value specifying callback priority,³⁰ default = 20
args - arbitrary value (any type) passed to the callback as cb_args each time it is invoked

Multiple user callbacks can be registered by assigning a cell array of such strings and/or structs to the cpf.user_callback option.

5.6.2 CPF Example

The following is an example of running a continuation power ﬂow using a version of the 9-bus system, looking at increasing all loads by a factor of 2.5. This example plots the nose curve shown in Figure 5-1.

Figure 5-1:Nose Curve of Voltage Magnitude at Bus 9

define_constants;
mpopt = mpoption('out.all', 0, 'verbose', 2);
mpopt = mpoption(mpopt, 'cpf.stop_at', 'FULL', 'cpf.step', 0.2);
mpopt = mpoption(mpopt, 'cpf.plot.level', 2);
mpcb = loadcase('t_case9_pfv2');                    % load base case
mpct = mpcb;                                        % set up target case with
mpct.gen(:, [PG QG]) = mpcb.gen(:, [PG QG]) * 2.5;  % increased generation
mpct.bus(:, [PD QD]) = mpcb.bus(:, [PD QD]) * 2.5;  % and increased load
results = runcpf(mpcb, mpct, mpopt);

This should result in something like the following output to the screen.

MATPOWER Version 7.0, 20-Jun-2019 -- AC Continuation Power Flow
step   0  :                      lambda =  0.000,  4 Newton steps
step   1  : stepsize = 0.2       lambda =  0.181   2 corrector Newton steps
step   2  : stepsize = 0.2       lambda =  0.359   2 corrector Newton steps
step   3  : stepsize = 0.2       lambda =  0.530   2 corrector Newton steps
step   4  : stepsize = 0.2       lambda =  0.693   3 corrector Newton steps
step   5  : stepsize = 0.2       lambda =  0.839   3 corrector Newton steps
step   6  : stepsize = 0.2       lambda =  0.952   3 corrector Newton steps
step   7  : stepsize = 0.2       lambda =  0.988   3 corrector Newton steps
step   8  : stepsize = 0.2       lambda =  0.899   3 corrector Newton steps
step   9  : stepsize = 0.2       lambda =  0.776   3 corrector Newton steps
step  10  : stepsize = 0.2       lambda =  0.654   3 corrector Newton steps
step  11  : stepsize = 0.2       lambda =  0.533   2 corrector Newton steps
step  12  : stepsize = 0.2       lambda =  0.413   2 corrector Newton steps
step  13  : stepsize = 0.2       lambda =  0.294   2 corrector Newton steps
step  14  : stepsize = 0.2       lambda =  0.176   2 corrector Newton steps
step  15  : stepsize = 0.2       lambda =  0.060   2 corrector Newton steps
step  16a : stepsize = 0.2       lambda = -0.054   2 corrector Newton steps ^ ROLLBACK
step  16  : stepsize = 0.0604    lambda =  0.000   3 corrector Newton steps
CPF TERMINATION: Traced full continuation curve in 16 continuation steps

The results of the continuation power ﬂow are then found in the cpf ﬁeld of the returned results struct.

>> results.cpf

ans =

         V_hat: [9x17 double]
       lam_hat: [1x17 double]
             V: [9x17 double]
           lam: [1x17 double]
         steps: [1x17 double]
    iterations: 16
       max_lam: 0.9876
        events: [1x1 struct]
      done_msg: 'Traced full continuation curve in 16 continuation steps'

[prev] [prev-tail] [front] [up]

name	description
results.cpf	CPF output struct whose content depends on any user callback functions, where default contains ﬁelds:
done_msg	string with message describing cause of continuation termination
events(eidx)	a structure array of size $ne$ , where $ne$ is the number of events located, with ﬁelds:
k	continuation step number at which event was located
name	name of event
idx	index(es) of critical elements in corresponding event function, e.g. index of generator reaching VAr limit
msg	descriptive text detailing the event
iterations	$nsteps$ , number of continuation steps performed
lam	$1× n$ vector of $λ$ values from correction steps^†
lam_hat	$1× n$ vector of $λ$ values from prediction steps^†
max_lam	maximum value of $λ$ found in results.cpf.lam
steps	$1× n$ vector of step sizes for each continuation step performed^†
V	$nb × n$ matrix of complex bus voltages from correction steps^†
V_hat	$nb × n$ matrix of complex bus voltages from prediction steps^†

name	default	description
cpf.parameterization	3	choice of parameterization
		1 — natural
		2 — arc length
		3 — pseudo arc length
cpf.stop_at	'NOSE'	determines stopping criterion
		'NOSE' — stop when nose point is reached
		'FULL' — trace full nose curve
		$λstop$ — stop upon reaching target $λ$ value $λstop$
cpf.enforce_p_lims	0	enforce gen active power limits
		0 — do not enforce limits
		1 — enforce limits
cpf.enforce_q_lims	0	enforce gen reactive power limits at expense of $Vm$
		0 — do not enforce limits
		1 — enforce limits
cpf.enforce_v_lims	0	enforce bus voltage magnitude limits
		0 — do not enforce limits
		1 — enforce limits
cpf.enforce_flow_lims	0	enforce branch MVA ﬂow limits
		0 — do not enforce limits
		1 — enforce limits
cpf.step	0.05	default value for continuation power ﬂow step size $σ$
cpf.step_min	$−4 10$	minimum allowed step size, $σmin$
cpf.step_max	0.2	maximum allowed step size, $σmax$
cpf.adapt_step	0	toggle adaptive step size feature
		0 — adaptive step size disabled
		1 — adaptive step size enabled
cpf.adapt_step_damping	0.7	damping factor $βcpf$ from (5.13) for adaptive step sizing
cpf.adapt_step_tol	$10−3$	tolerance $𝜖 cpf$ from (5.13) for adaptive step sizing
cpf.target_lam_tol	$10−5$	tolerance for target lambda detection
cpf.nose_tol	$10−5$	tolerance for nose point detection (p.u.)
cpf.p_lims_tol	$10−2$	tolerance for generator active power limit detection (MW)
cpf.q_lims_tol	$10−2$	tolerance for generator reactive power limit detection (MVAr)
cpf.v_lims_tol	$10−4$	tolerance for bus voltage magnitude limit detection (p.u)
cpf.flow_lims_tol	0.01	tolerance for branch ﬂow limit detection (MVA)
cpf.plot.level	0	control plotting of nose curve
		0 — do not plot nose curve
		1 — plot when completed
		2 — plot incrementally at each iteration
		3 — same as 2, with pause at each iteration
cpf.plot.bus	empty	index of bus whose voltage is to be plotted
cpf.user_callback	empty	string or cell array of strings with names of user callback functions^†

name	description
k	continuation step iteration count
nx	next CPF state^*,corresponding to proposed next step
cx	current CPF state^*,corresponding to most recent successful step
px	previous CPF state^*,corresponding to last successful step prior to cx
done	struct, with ﬂag to indicate CPF termination and reason, with ﬁelds:
.flag	termination ﬂag, 1 $→$ terminate, 0 $→$ continue
.msg	string containing reason for termination
rollback	scalar ﬂag to indicate that the current step should be rolled back and retried with a diﬀerent step size, etc.
evnts	struct array listing any events detected for this step^‡
cb_data	struct containing static data^§ , with the following ﬁelds (all based on internal indexing):
.mpc_base	Matpower case struct of base case
.mpc_target	Matpower case struct of target case
.Sbusb	handle of function returning $nb × 1$ vector of complex base case bus injections in p.u. and derivatives w.r.t. $\|V \|$
.Sbust	handle of function returning $nb × 1$ vector of complex target case bus injections in p.u. and derivatives w.r.t. $\|V \|$
.Ybus	bus admittance matrix
.Yf	branch admittance matrix, “from” end of branches
.Yt	branch admittance matrix, “to” end of branches
.pv	list of indices of PV buses
.pq	list of indices of PQ buses
.ref	list of indices of reference buses
.idx_pmax	vector of gen indices of gens at PMAX
.mpopt	Matpower options struct
cb_args	arbitrary data structure containing user-provided callback arguments
results	initial value of output struct to be assigned to cpf ﬁeld of results struct returned by runcpf

name	description
lam_hat	value of $λ$ after predictor step
V_hat	vector of complex bus voltages after predictor step
lam	value of $λ$ after corrector step
V	vector of complex bus voltages after corrector step
z	normalized tangent predictor, $z¯$
default_step	default step size
default_parm	default parameterization^*
this_step	step size for this step only
this_parm	parameterization^* for this step only
step	current step size
parm	current parameterization^*
events	event log
cb	user state for callbacks^† , a user-deﬁned struct containing any information a callback function would like to pass from one invokation to the next
ef	cell array of event function values