runcpf

runcpf(basecasedata, targetcasedata, mpopt, fname, solvedcase)

runcpf() - Runs a full AC continuation power flow

[RESULTS, SUCCESS] = RUNCPF(BASECASEDATA, TARGETCASEDATA, ...
                                MPOPT, FNAME, SOLVEDCASE)

Runs a full AC continuation power flow using a normalized tangent
predictor and selected parameterization scheme, optionally
returning a RESULTS struct and SUCCESS flag. Step size can be
fixed or adaptive.

Inputs (all are optional):
    BASECASEDATA : either a MATPOWER case struct or a string containing
        the name of the file with the case data defining the base loading
        and generation (default is 'case9')
        (see CASEFORMAT and LOADCASE)
    TARGETCASEDATA : either a MATPOWER case struct or a string
        containing the name of the file with the case data defining the
        target loading and generation (default is 'case9target')
    MPOPT : MATPOWER options struct to override default options
        can be used to specify the parameterization, output options,
        termination criteria, and more (see MPOPTION).
    FNAME : name of a file to which the pretty-printed output will
        be appended
    SOLVEDCASE : name of file to which the solved case will be saved
        in MATPOWER case format (M-file will be assumed unless the
        specified name ends with '.mat')

Outputs (all are optional):
    RESULTS : results struct, with the following fields:
        (all fields from the input MATPOWER case, i.e. bus, branch,
            gen, etc., but with solved voltages, power flows, etc.)
        order - info used in external <-> internal data conversion
        et - elapsed time in seconds
        success - success flag, 1 = succeeded, 0 = failed
        cpf - CPF output struct whose content depends on any
                user callback functions, where default contains fields:
            done_msg - string with message describing cause of
                    continuation termination
            iterations - number of continuation steps performed
            lam - (nsteps+1) row vector of lambda values from
                    correction steps
            lam_hat - (nsteps+1) row vector of lambda values from
                    prediction steps
            max_lam - maximum value of lambda in RESULTS.cpf.lam
            steps - (nsteps+1) row vector of stepsizes taken at each
                    continuation step
            V - (nb x nsteps+1) complex bus voltages from
                    correction steps
            V_hat - (nb x nsteps+1) complex bus voltages from
                    prediction steps
            events - an array of structs of size nevents with the
                following fields:
                 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
    SUCCESS : the success flag can additionally be returned as
        a second output argument

Calling syntax options:
    results = runcpf;
    results = runcpf(basecasedata, targetcasedata);
    results = runcpf(basecasedata, targetcasedata, mpopt);
    results = runcpf(basecasedata, targetcasedata, mpopt, fname);
    results = runcpf(basecasedata, targetcasedata, mpopt, fname, solvedcase)
    [results, success] = runcpf(...);

If the 'cpf.enforce_q_lims' option is set to true (default is false) then,
if any generator reaches its reactive power limits during the AC
continuation power flow,
    - the corresponding bus is converted to a PQ bus, and the problem
      is modified to eliminate further reactive transfer on this bus
    - the voltage magnitude at the bus will deviate from the specified
      setpoint to satisfy the reactive power limit,
    - if the reference bus is converted to PQ, further real power transfer
      for the bus is also eliminated, and the first remaining PV bus is
      selected as the new slack, resulting in the transfers at both
      reference buses potentially deviating from the specified values
    - if all reference and PV buses are converted to PQ, RUNCPF terminates
      with an infeasibility message.

If the 'cpf.enforce_p_lims' option is set to true (default is fals) then,
if any generator reaches its maximum active power limit during the AC
continuation power flow,
    - the problem is modified to eliminate further active transfer by
      this generator
    - if the generator was at the reference bus, it is converted to PV
      and the first remaining PV bus is selected as the new slack.

If the 'cpf.enforce_v_lims' option is set to true (default is false)
then the continuation power flow is set to terminate if any bus voltage
magnitude exceeds its minimum or maximum limit.

If the 'cpf.enforce_flow_lims' option is set to true (default is false)
then the continuation power flow is set to terminate if any line MVA
flow exceeds its rateA limit.

Possible CPF termination modes:
    when cpf.stop_at == 'NOSE'
        - Reached steady state loading limit
        - Nose point eliminated by limit induced bifurcation
    when cpf.stop_at == 'FULL'
        - Traced full continuation curve
    when cpf.stop_at == <target_lam_val>
        - Reached desired lambda
    when cpf.enforce_p_lims == true
        - All generators at PMAX
    when cpf.enforce_q_lims == true
        - No REF or PV buses remaining
    when cpf.enforce_v_lims == true
        - Any bus voltage magnitude limit is reached
    when cpf.enforce_flow_lims == true
        - Any branch MVA flow limit is reached
    other
        - Base case power flow did not converge
        - Base and target case have identical load and generation
        - Corrector did not converge
        - Could not locate <event_name> event
        - Too many rollback steps triggered by callbacks

Examples:
    results = runcpf('case9', 'case9target');
    results = runcpf('case9', 'case9target', ...
                        mpoption('cpf.adapt_step', 1));
    results = runcpf('case9', 'case9target', ...
                        mpoption('cpf.enforce_q_lims', 1));
    results = runcpf('case9', 'case9target', ...
                        mpoption('cpf.stop_at', 'FULL'));

See also mpoption(), runpf().