ADD_COSTS Adds a set of user costs to the model.
OM = ADD_COSTS(OM, NAME, CP, VARSETS);
Adds a named block of user-defined costs to the model. Each set is
defined by the CP struct described below. All user-defined sets of
costs are combined together into a single set of cost parameters in
a single CP struct by BULD_COST_PARAMS. This full aggregate set of
cost parameters can be retreived from the model by GET_COST_PARAMS.
Examples:
cp1 = struct('N', N1, 'Cw', Cw1);
cp2 = struct('N', N2, 'Cw', Cw2, 'H', H, 'dd', dd, ...
'rh', rh, 'kk', kk, 'mm', mm);
om = add_costs(om, 'usr1', cp1, {'Pg', 'Qg', 'z'});
om = add_costs(om, 'usr2', cp2, {'Vm', 'Pg', 'Qg', 'z'});
Let x refer to the vector formed by combining the specified VARSETS,
and f_u(x, CP) be the cost at x corresponding to the cost parameters
contained in CP, where CP is a struct with the following fields:
N - nw x nx sparse matrix
Cw - nw x 1 vector
H - nw x nw sparse matrix (optional, all zeros by default)
dd, mm - nw x 1 vectors (optional, all ones by default)
rh, kk - nw x 1 vectors (optional, all zeros by default)
These parameters are used as follows to compute f_u(x, CP)
R = N*x - rh
/ kk(i), R(i) < -kk(i)
K(i) = < 0, -kk(i) <= R(i) <= kk(i)
\ -kk(i), R(i) > kk(i)
RR = R + K
U(i) = / 0, -kk(i) <= R(i) <= kk(i)
\ 1, otherwise
DDL(i) = / 1, dd(i) = 1
\ 0, otherwise
DDQ(i) = / 1, dd(i) = 2
\ 0, otherwise
Dl = diag(mm) * diag(U) * diag(DDL)
Dq = diag(mm) * diag(U) * diag(DDQ)
w = (Dl + Dq * diag(RR)) * RR
f_u(x, CP) = 1/2 * w'*H*w + Cw'*w
See also OPF_MODEL, BUILD_COST_PARAMS, GET_COST_PARAMS, COMPUTE_COST.0001 function om = add_costs(om, name, cp, varsets) 0002 %ADD_COSTS Adds a set of user costs to the model. 0003 % OM = ADD_COSTS(OM, NAME, CP, VARSETS); 0004 % 0005 % Adds a named block of user-defined costs to the model. Each set is 0006 % defined by the CP struct described below. All user-defined sets of 0007 % costs are combined together into a single set of cost parameters in 0008 % a single CP struct by BULD_COST_PARAMS. This full aggregate set of 0009 % cost parameters can be retreived from the model by GET_COST_PARAMS. 0010 % 0011 % Examples: 0012 % cp1 = struct('N', N1, 'Cw', Cw1); 0013 % cp2 = struct('N', N2, 'Cw', Cw2, 'H', H, 'dd', dd, ... 0014 % 'rh', rh, 'kk', kk, 'mm', mm); 0015 % om = add_costs(om, 'usr1', cp1, {'Pg', 'Qg', 'z'}); 0016 % om = add_costs(om, 'usr2', cp2, {'Vm', 'Pg', 'Qg', 'z'}); 0017 % 0018 % Let x refer to the vector formed by combining the specified VARSETS, 0019 % and f_u(x, CP) be the cost at x corresponding to the cost parameters 0020 % contained in CP, where CP is a struct with the following fields: 0021 % N - nw x nx sparse matrix 0022 % Cw - nw x 1 vector 0023 % H - nw x nw sparse matrix (optional, all zeros by default) 0024 % dd, mm - nw x 1 vectors (optional, all ones by default) 0025 % rh, kk - nw x 1 vectors (optional, all zeros by default) 0026 % 0027 % These parameters are used as follows to compute f_u(x, CP) 0028 % 0029 % R = N*x - rh 0030 % 0031 % / kk(i), R(i) < -kk(i) 0032 % K(i) = < 0, -kk(i) <= R(i) <= kk(i) 0033 % \ -kk(i), R(i) > kk(i) 0034 % 0035 % RR = R + K 0036 % 0037 % U(i) = / 0, -kk(i) <= R(i) <= kk(i) 0038 % \ 1, otherwise 0039 % 0040 % DDL(i) = / 1, dd(i) = 1 0041 % \ 0, otherwise 0042 % 0043 % DDQ(i) = / 1, dd(i) = 2 0044 % \ 0, otherwise 0045 % 0046 % Dl = diag(mm) * diag(U) * diag(DDL) 0047 % Dq = diag(mm) * diag(U) * diag(DDQ) 0048 % 0049 % w = (Dl + Dq * diag(RR)) * RR 0050 % 0051 % f_u(x, CP) = 1/2 * w'*H*w + Cw'*w 0052 % 0053 % See also OPF_MODEL, BUILD_COST_PARAMS, GET_COST_PARAMS, COMPUTE_COST. 0054 0055 % MATPOWER 0056 % $Id: add_costs.m,v 1.7 2010/04/26 19:45:25 ray Exp $ 0057 % by Ray Zimmerman, PSERC Cornell 0058 % Copyright (c) 2008-2010 by Power System Engineering Research Center (PSERC) 0059 % 0060 % This file is part of MATPOWER. 0061 % See http://www.pserc.cornell.edu/matpower/ for more info. 0062 % 0063 % MATPOWER is free software: you can redistribute it and/or modify 0064 % it under the terms of the GNU General Public License as published 0065 % by the Free Software Foundation, either version 3 of the License, 0066 % or (at your option) any later version. 0067 % 0068 % MATPOWER is distributed in the hope that it will be useful, 0069 % but WITHOUT ANY WARRANTY; without even the implied warranty of 0070 % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 0071 % GNU General Public License for more details. 0072 % 0073 % You should have received a copy of the GNU General Public License 0074 % along with MATPOWER. If not, see <http://www.gnu.org/licenses/>. 0075 % 0076 % Additional permission under GNU GPL version 3 section 7 0077 % 0078 % If you modify MATPOWER, or any covered work, to interface with 0079 % other modules (such as MATLAB code and MEX-files) available in a 0080 % MATLAB(R) or comparable environment containing parts covered 0081 % under other licensing terms, the licensors of MATPOWER grant 0082 % you additional permission to convey the resulting work. 0083 0084 %% prevent duplicate named cost sets 0085 if isfield(om.cost.idx.N, name) 0086 error('@opf_model/add_costs: cost set named ''%s'' already exists', name); 0087 end 0088 0089 if nargin < 4 0090 varsets = {}; 0091 end 0092 if isempty(varsets) 0093 varsets = om.var.order; 0094 end 0095 [nw, nx] = size(cp.N); 0096 0097 %% check sizes 0098 nv = 0; 0099 for k = 1:length(varsets) 0100 nv = nv + om.var.idx.N.(varsets{k}); 0101 end 0102 if nx ~= nv 0103 if nw == 0 0104 cp.N = sparse(nw, nx); 0105 else 0106 error('@opf_model/add_costs: number of columns in N (%d x %d) does not match\nnumber of variables (%d)\n', nw, nx, nv); 0107 end 0108 end 0109 if size(cp.Cw, 1) ~= nw 0110 error('@opf_model/add_costs: number of rows of Cw (%d x %d) and N (%d x %d) must match\n', size(cp.Cw), nw, nx); 0111 end 0112 if isfield(cp, 'H') && (size(cp.H, 1) ~= nw || size(cp.H, 2) ~= nw) 0113 error('@opf_model/add_costs: both dimensions of H (%d x %d) must match the number of rows in N (%d x %d)\n', size(cp.H), nw, nx); 0114 end 0115 if isfield(cp, 'dd') && size(cp.dd, 1) ~= nw 0116 error('@opf_model/add_costs: number of rows of dd (%d x %d) and N (%d x %d) must match\n', size(cp.dd), nw, nx); 0117 end 0118 if isfield(cp, 'rh') && size(cp.rh, 1) ~= nw 0119 error('@opf_model/add_costs: number of rows of rh (%d x %d) and N (%d x %d) must match\n', size(cp.rh), nw, nx); 0120 end 0121 if isfield(cp, 'kk') && size(cp.kk, 1) ~= nw 0122 error('@opf_model/add_costs: number of rows of kk (%d x %d) and N (%d x %d) must match\n', size(cp.kk), nw, nx); 0123 end 0124 if isfield(cp, 'mm') && size(cp.mm, 1) ~= nw 0125 error('@opf_model/add_costs: number of rows of mm (%d x %d) and N (%d x %d) must match\n', size(cp.mm), nw, nx); 0126 end 0127 0128 %% add info about this user cost set 0129 om.cost.idx.i1.(name) = om.cost.N + 1; %% starting index 0130 om.cost.idx.iN.(name) = om.cost.N + nw; %% ending index 0131 om.cost.idx.N.(name) = nw; %% number of costs (nw) 0132 om.cost.data.N.(name) = cp.N; 0133 om.cost.data.Cw.(name) = cp.Cw; 0134 om.cost.data.vs.(name) = varsets; 0135 if isfield(cp, 'H') 0136 om.cost.data.H.(name) = cp.H; 0137 end 0138 if isfield(cp, 'dd') 0139 om.cost.data.dd.(name) = cp.dd; 0140 end 0141 if isfield(cp, 'rh') 0142 om.cost.data.rh.(name) = cp.rh; 0143 end 0144 if isfield(cp, 'kk') 0145 om.cost.data.kk.(name) = cp.kk; 0146 end 0147 if isfield(cp, 'mm') 0148 om.cost.data.mm.(name) = cp.mm; 0149 end 0150 0151 %% update number of vars and var sets 0152 om.cost.N = om.cost.idx.iN.(name); 0153 om.cost.NS = om.cost.NS + 1; 0154 0155 %% put name in ordered list of var sets 0156 om.cost.order{om.cost.NS} = name;