7.1 Direct Specification

This section describes the additional fields that can be added to mpc (the Matpower case struct) or, alternatively, the input parameters that can be passed directly to the opf function. The former is the preferred approach, as it allows the normal use of runopf and related functions.

7.1.1 User-defined Variables

In the case of direct specification, additional variables are created implicitly based on the difference between the number of columns in and the number of standard OPF variables. If has more columns than has elements, the extra columns are assumed to correspond to a new variable. The initial value and lower and upper bounds for can also be specified in the optional fields or arguments, z0, zl and zu, respectively.

7.1.2 User-defined Constraints

• Linear Constraints can be added by specifying the , and parameters of (6.38) directly as fields or arguments of the same names, A, l and u, respectively, where A is sparse.
• Nonlinear Constraints for a constraint set , that is, or from (6.42) or (6.43), are implemented by defining two M-file functions, similar to those required by MIPS. The first is a function to compute the constraint values and their gradients (Jacobian),⁴⁶ with calling syntax:

  [g, dg] = my_constraint_fcn(x, <p1>, <p2>, ...)
  
  Here <p1> and <p2> represent arbitrary optional input parameters that remain constant for all calls to the function. The second is a function to compute the Hessian of the corresponding term in the Lagrangian function, that is the term corresponding to or . This function has the following calling syntax:

  d2G = my_constraint_hess(x, lambda, <p1>, <p2>, ...)
  
  Once again this is similar to the form of the Hessian evaluation function expected by MIPS.⁴⁷

  In order to add a set of user-defined nonlinear constraints to the formulation through direct specification, an entry must be added to the optional user_constraints.nle (nonlinear equality) or user_constraints.nli (nonlinear inequality) fields of the Matpower case struct. These fields are cell arrays, in which each element (also a cell array) specifies a constraint set of the corresponding kind. The format is as follows, where the details are described in Table 7-1.

  mpc.user_constraints.nle = {
      {name, N, g_fcn, hess_fcn, varsets, params},
      ...
  };

  name	description
  name	string with name of constraint set, used to label multipliers in results struct
  N	number of constraints, i.e. dimension of (or as the case may be)
  g_fcn	string containing name of function to evaluate constraint and gradients (Jacobian)
  hess_fcn	string containing name of function to evaluate Hessian of corresponding term of Lagrangian
  varsets	cell array of variable set names, specifying sub-vectors of optimization vector to be passed as inputs in x†
  params	cell array of optional, arbitrary parameters to pass to each call to the constraint and Hessian evaluation functions

  ^† If varsets is empty, x will be the full optimization vector , otherwise it will be a cell array of sub-vectors of for the specified variable sets. Valid names include 'Va', 'Vm', 'Pg', and 'Qg'. It can include others depending on the OPF extensions in use. See the variable names displayed by results.om for a complete list for your problem.

  There is an example in the OPF testing code (e.g. t_opf_mips) near the end, that implements a nonlinear relationship between three different generator outputs by adding the following line.

  mpc.user_constraints.nle = {
      {'Pg_usr', 1, 'opf_nle_fcn1', 'opf_nle_hess1', {'Pg'}, {}}
  };

  This adds a single constraint named 'Pg_usr' as a function of the vector of generator active injections (x will be {Pg}, where Pg is a sub-vector of the optimization vector containing only the generator active injections). The constraints and gradients are evaluated by a function named 'opf_nle_fcn1' and the Hessian of the corresponding term of the Lagrangian by a function named 'opf_nle_hess1', neither of which expect any additional parameters.

7.1.3 User-defined Costs

• Quadratic Costs by direct specification are not currently supported.
• General Nonlinear Costs by direct specification are not currently supported.
• Legacy Costs – To add legacy costs directly, the parameters , , , , , and of (6.48)–(6.51) described in Section 6.3.3 are specified as fields or arguments H, Cw, N and fparm, respectively, where fparm is the matrix

  (7.1)

  When specifying additional costs, N and Cw are required, while H and fparm are optional. The default value for is a zero matrix, and the default for is such that and are all ones and and are all zeros, resulting in simple linear cost, with no shift or “dead-zone”. N and H should be specified as sparse matrices.

7.1.4 Additional Comments

For a simple formulation extension to be used for a small number of OPF cases, this method has the advantage of being direct and straightforward. While Matpower does include code to eliminate the columns of and corresponding to and when running a DC OPF⁴⁸ , as well as code to reorder and eliminate columns appropriately when converting from external to internal data formats, this mechanism still requires the user to take special care in preparing the and matrices to ensure that the columns match the ordering of the elements of the optimization vectors and . All extra constraints and variables must be incorporated into a single set of parameters that are constructed before calling the OPF. The bookkeeping needed to access the resulting variables and shadow prices on constraints and variable bounds must be handled manually by the user outside of the OPF, along with any processing of additional input data and processing, printing or saving of the additional result data. Making further modifications to a formulation that already includes user-supplied costs, constraints or variables, requires that both sets be incorporated into a new single consistent set of parameters.