toggle_softlims

toggle_softlims(mpc, on_off)
toggle_softlims() - Relax DC optimal power flow branch limits.
MPC = TOGGLE_SOFTLIMS(MPC, 'on')
MPC = TOGGLE_SOFTLIMS(MPC, 'off')
T_F = TOGGLE_SOFTLIMS(MPC, 'status')

Enables, disables or checks the status of a set of OPF userfcn
callbacks to implement relaxed inequality constraints for an OPF model.

These callbacks expect to find a 'softlims' field in the input MPC,
where MPC.softlims is a struct with fields corresponding to the
possible limits, namely:
    VMIN, VMAX, RATE_A, PMIN, PMAX, QMIN, QMAX, ANGMAX, ANGMIN
Each of these is itself a struct with the following fields, all of which
are optional:
    idx     index of affected buses, branches, or generators. These are
            row indices into the respective matrices. The default is to
            include all online elements for which the constraint in
            question is not unbounded, except for generators, which also
            exclude those used to model dispatchable loads
            (i.e. those for which isload(gen) is true).
    busnum  for bus constraints, such as VMIN and VMAX, the affected
            buses can be specified by a vector of external bus numbers
            in the 'busnum' field instead of bus row indices in the 'idx'
            field. If both are present, 'idx' overrides 'busnum'.
    cost    linear marginal cost of exceeding the original limit
            The defaults are set as:
                base_cost x 100 $/pu    for VMAX and VMIN
                base_cost $/MW          for RATE_A, PMAX, and PMIN
                base_cost $/MVAr        for QMAX, QMIN
                base_cost $/deg         for ANGMAX, ANGMIN
            where base_cost is the maximum of $1000 and twice the
            maximum generator cost of all online generators.
    hl_mod  type of modification to hard limit, hl:
                'none'    : do *not* add soft limit, no change to original
                            hard limit
                'remove'  : add soft limit, relax hard limit by removing
                            it completely
                'replace' : add soft limit, relax hard limit by replacing
                            original with value specified in hl_val
                'scale'   : add soft limit, relax hard limit by scaling
                            original by value specified in hl_val
                'shift'   : add soft limit, relax hard limit by shifting
                            original by value specified in hl_val
    hl_val  value used to modify hard limit according to hl_mod. Ignored
            for 'none' and 'remove', required for 'replace', and optional,
            with the following defaults, for 'scale' and 'shift':
                'scale' :   2 for positive upper limits or negative lower
                            limits, 0.5 otherwise
                'shift' :   0.25 for VMAX and VMIN, 10 otherwise

For limits that are left unspecified in the structure, the default
behavior is determined by the value of the mpopt.opf.softlims.default
option. If mpopt.opf.softlims.default = 0, then the unspecified softlims
are ignored (hl_mod = 'none', i.e. original hard limits left in place).
If mpopt.opf.softlims.default = 1 (default), then the unspecified
softlims are enabled with default values, which specify to 'remove'
the hard limit, except in the case of VMIN and PMIN, whose defaults
are set as follows:
      .VMIN
        .hl_mod = 'replace'
        .hl_val = 0
      .PMIN
        .hl_mod = 'replace'
        .hl_val = 0     for normal generators (PMIN > 0)
        .hl_val = -Inf  for for generators with PMIN < 0 AND PMAX > 0

With mpopt.opf.softlims.default = 0, it is still possible to enable a
softlim with default values by setting that specification to an empty
struct. E.g. mpc.softlims.VMAX = struct() would enable a default
softlim on VMAX.

The 'int2ext' callback also packages up results and stores them in
the following output fields of results.softlims.(lim), where lim is
one of the above mentioned limits:
    overload - amount of overload, i.e. violation of hard-limit.
    ovl_cost - total cost of overload in $/hr

The shadow prices on the soft limit constraints are also returned in the
relevant columns of the respective matrices (MU_SF, MU_ST for RATE_A,
MU_VMAX for VMAX, etc.)
Note: These shadow prices are equal to the corresponding hard limit
    shadow prices when the soft limits are not violated. When violated,
    the shadow price on a soft limit constraint is equal to the
    user-specified soft limit violation cost + the shadow price on any
    binding remaining hard limit.