cpf_default_callback
- cpf_default_callback(k, nx, cx, px, done, rollback, evnts, cb_data, cb_args, results)
cpf_default_callback()
- Default callback function for CPF.[NX, CX, DONE, ROLLBACK, EVNTS, CB_DATA, RESULTS] = CPF_DEFAULT_CALLBACK(K, NX, CX, PX, DONE, ROLLBACK, EVNTS, ... CB_DATA, CB_ARGS, RESULTS) Default callback function used by RUNCPF that collects the results and optionally, plots the nose curve. Inputs and outputs are defined below, with the RESULTS argument being optional, used only for the final call when K is negative. Inputs: K - continuation step iteration count NX - next state (corresponding to proposed next step), struct with the following fields: lam_hat - value of LAMBDA from predictor V_hat - vector of complex bus voltages from predictor lam - value of LAMBDA from corrector V - vector of complex bus voltages from corrector z - normalized tangent predictor default_step - default step size default_parm - default parameterization this_step - step size for this step only this_parm - paramterization for this step only step - current step size parm - current parameterization events - struct array, event log cb - user state, for callbacks (replaces CB_STATE), the user may add fields containing any information the callback function would like to pass from one invokation to the next, taking care not to step on fields being used by other callbacks, such as the 'default' field used by this default callback ef - cell array of event function values CX - current state (corresponding to most recent successful step) (same structure as NX) PX - previous state (corresponding to last successful step prior to CX) DONE - struct, with flag to indicate CPF termination and reason, with fields: flag - termination flag, 1 => terminate, 0 => continue msg - string containing reason for termination ROLLBACK - scalar flag to indicate that the current step should be rolled back and retried with a different step size, etc. EVNTS - struct array listing any events detected for this step, see CPF_DETECT_EVENTS for details CB_DATA - struct containing potentially useful "static" data, with the following fields (all based on internal indexing): mpc_base - MATPOWER case struct of base state mpc_target - MATPOWER case struct of target state Sbusb - handle of function returning nb x 1 vector of complex base case injections in p.u. and derivatives w.r.t. |V| Sbust - handle of function returning nb x 1 vector of complex target case 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 - vector of indices of PV buses pq - vector of indices of PQ buses ref - vector of indices of REF buses idx_pmax - vector of generator indices for generators fixed at their PMAX limits mpopt - MATPOWER options struct CB_ARGS - arbitrary data structure containing callback arguments RESULTS - initial value of output struct to be assigned to CPF field of results struct returned by RUNCPF Outputs: (all are updated versions of the corresponding input arguments) NX - user state ('cb' field ) should be updated here if ROLLBACK is false CX - 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 field ROLLBACK - callback can request a rollback step, even if it was not indicated by an event function EVNTS - msg field for a given event may be updated CB_DATA - this data should only be modified if the underlying problem has been changed (e.g. generator limit reached) and should always be followed by a step of zero length, i.e. set NX.this_step to 0 It is the job of any callback modifying CB_DATA to ensure that all data in CB_DATA is kept consistent. RESULTS - updated version of RESULTS input arg This function is called in three different contexts, distinguished by the value of K, as follows: (1) initial - called with K = 0, without RESULTS input/output args, after base power flow, before 1st CPF step. (2) iterations - called with K > 0, without RESULTS input/output args, at each iteration, after predictor-corrector step (3) final - called with K < 0, with RESULTS input/output args, after exiting predictor-corrector loop, inputs identical to last iteration call, except K which is negated User Defined CPF Callback Functions: The user can define their own callback functions which take the same form and are called in the same contexts as CPF_DEFAULT_CALLBACK. These 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: 'fcn' - string with name of callback function 'priority' - numerical value specifying callback priority (default = 20, see CPF_REGISTER_CALLBACK for details) '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.
See also
runcpf()
,cpf_register_callback()
.