5.6 runcpf

In Matpower, a continuation power flow is executed by calling runcpf with two Matpower cases (case structs or case file names) as the first two arguments, basecasedata and targetcasedata, respectively. The first contains the base loading/generation profile while the second contains the target loading/generation profile. 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 file 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 fields as well as additional columns in some of the existing data fields. In addition to the solution values included in the results for a simple power flow, shown in Table 4-1 in Section 4.4, the following additional continuation power flow solution values are stored in the cpf field as shown in Table 5-1.

Table 5-1:Continuation Power Flow Results



CPF output struct whose content depends on any user callback functions, where default contains fields:


string with message describing cause of continuation termination


a structure array of size ne  , where ne  is the number of events located, with fields:


continuation step number at which event was located


name of event


index(es) of critical elements in corresponding event function, e.g. index of generator reaching VAr limit


descriptive text detailing the event


nsteps  , number of continuation steps performed


1× n  vector of λ  values from correction steps


1× n  vector of λ  values from prediction steps


maximum value of λ  found in results.cpf.lam


1× n  vector of step sizes for each continuation step performed


nb × n  matrix of complex bus voltages from correction steps


nb × n  matrix of complex bus voltages from prediction steps

n  is one more than the number of continuation steps, i.e. nsteps+ 1  , so the first element corresponds to the starting point.

The options that control the continuation power flow simulation are listed in Table 5-2. All the power flow 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 flow.

Table 5-2:Continuation Power Flow Options
name default


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 flow limits

 0 — do not enforce limits

 1 — enforce limits

cpf.step 0.05

default value for continuation power flow step size σ

cpf.step_min   −4

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 flow 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

See help cpf_default_callback for details.

5.6.1 CPF Callback Functions

Matpower’s continuation power flow 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 different contexts, distinguished by the value of the first argument k as follows:

initial – called with k = 0, without results input/output arguments, after base power flow, before first CPF step.
iterations – called with k > 0  , without results input/output arguments, at each iteration, after predictor-corrector step
final – 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




continuation step iteration count


next CPF state*,corresponding to proposed next step


current CPF state*,corresponding to most recent successful step


previous CPF state*,corresponding to last successful step prior to cx


struct, with flag to indicate CPF termination and reason, with fields:


termination flag, 1 → terminate, 0 → continue


string containing reason for termination


scalar flag to indicate that the current step should be rolled back and retried with a different step size, etc.


struct array listing any events detected for this step


struct containing static data§ , with the following fields (all based on internal indexing):


Matpower case struct of base case


Matpower case struct of target case


handle of function returning nb × 1  vector of complex base case bus injections in p.u. and derivatives w.r.t. |V |


handle of function returning nb × 1  vector of complex target case bus injections in p.u. and derivatives w.r.t. |V |


bus admittance matrix


branch admittance matrix, “from” end of branches


branch admittance matrix, “to” end of branches


list of indices of PV buses


list of indices of PQ buses


list of indices of reference buses


vector of gen indices of gens at PMAX


Matpower options struct


arbitrary data structure containing user-provided callback arguments


initial value of output struct to be assigned to cpf field of results struct returned by runcpf

* See Table 5-5 for details of the CPF state. See cpf_detect_events for details of the evnts field. § Please note that any callback that modifies the underlying problem is responsible to update the contents of cb_data accordingly. E.g. converting a bus from PV to PQ requires updates to mpc_base, mpc_target, Sbusb, Sbust, pv, pq, and possibly ref. So, cb_data should only be thought of as static for a fixed base and target case pair.

Table 5-4:Continuation Power Flow Callback Output Arguments



All are updated versions of the corresponding input arguments, see Table 5-3 for more details.


next CPF state*,user state (cb field) should be updated here if rollback is false


current CPF state*,may contain updated this_step or this_parm values to be used if rollback is true


callback may have requested termination and set the msg field


callback can request a rollback step, even if it was not indicated by an event function


msg field for a given event may be updated


this data should only be modified 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§


updated version of results input argument to be assigned to cpf field 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 fields in cx. See cpf_detect_events for details of the evnts field. § It is the job of any callback modifying cb_data to ensure that all data in cb_data is kept consistent.

Table 5-5:Continuation Power Flow State




value of λ  after predictor step


vector of complex bus voltages after predictor step


value of λ  after corrector step


vector of complex bus voltages after corrector step


normalized tangent predictor, z¯


default step size


default parameterization*


step size for this step only


parameterization*  for this step only


current step size


current parameterization*


event log


user state for callbacks , a user-defined struct containing any information a callback function would like to pass from one invokation to the next


cell array of event function values

* Corresponding to the cpf.parameterization option in Table 5-2. Replaces cb_state from Matpower 5.

The user can define their own callback functions which take the same form and are called in the same contexts as cpf_default_callback. User callback functions are specified 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 fields, where all but the first are optional:

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 flow 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
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 flow are then found in the cpf field 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'