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().