ADD_USERFCN Appends a userfcn to the list to be called for a case.
MPC = ADD_USERFCN(MPC, STAGE, FCN)
MPC = ADD_USERFCN(MPC, STAGE, FCN, ARGS)
MPC = ADD_USERFCN(MPC, STAGE, FCN, ARGS, ALLOW_MULTIPLE)
A userfcn is a callback function that can be called automatically by
MATPOWER at one of various stages in a simulation.
MPC : the case struct
STAGE : the name of the stage at which this function should be
called: ext2int, formulation, int2ext, printpf
FCN : the name of the userfcn
ARGS : (optional) the value to be passed as an argument to the
userfcn (typically a struct)
ALLOW_MULTIPLE : (optional) if TRUE, allows the same function to
be added more than once.
Currently there are 5 different callback stages defined. Each stage has
a name, and by convention, the name of a user-defined callback function
ends with the name of the stage. The following is a description of each
stage, when it is called and the input and output arguments which vary
depending on the stage. The reserves example (see RUNOPF_W_RES) is used
to illustrate how these callback userfcns might be used.
1. ext2int
Called from EXT2INT immediately after the case is converted from
external to internal indexing. Inputs are a MATPOWER case struct (MPC),
freshly converted to internal indexing and any (optional) ARGS value
supplied via ADD_USERFCN. Output is the (presumably updated) MPC. This is
typically used to reorder any input arguments that may be needed in
internal ordering by the formulation stage.
E.g. mpc = userfcn_reserves_ext2int(mpc, args)
2. formulation
Called from OPF after the OPF Model (OM) object has been initialized
with the standard OPF formulation, but before calling the solver. Inputs
are the OM object and any (optional) ARGS supplied via ADD_USERFCN.
Output is the OM object. This is the ideal place to add any additional
vars, constraints or costs to the OPF formulation.
E.g. om = userfcn_reserves_formulation(om, args)
3. int2ext
Called from INT2EXT immediately before the resulting case is converted
from internal back to external indexing. Inputs are the RESULTS struct
and any (optional) ARGS supplied via ADD_USERFCN. Output is the RESULTS
struct. This is typically used to convert any results to external
indexing and populate any corresponding fields in the RESULTS struct.
E.g. results = userfcn_reserves_int2ext(results, args)
4. printpf
Called from PRINTPF after the pretty-printing of the standard OPF
output. Inputs are the RESULTS struct, the file descriptor to write to,
a MATPOWER options struct, and any (optional) ARGS supplied via
ADD_USERFCN. Output is the RESULTS struct. This is typically used for
any additional pretty-printing of results.
E.g. results = userfcn_reserves_printpf(results, fd, mpopt, args)
5. savecase
Called from SAVECASE when saving a case struct to an M-file after
printing all of the other data to the file. Inputs are the case struct,
the file descriptor to write to, the variable prefix (typically 'mpc.')
and any (optional) ARGS supplied via ADD_USERFCN. Output is the case
struct. This is typically used to write any non-standard case struct
fields to the case file.
E.g. mpc = userfcn_reserves_printpf(mpc, fd, prefix, args)
See also RUN_USERFCN, REMOVE_USERFCN, TOGGLE_RESERVES, TOGGLE_IFLIMS,
TOGGLE_DCLINE, TOGGLE_SOFTLIMS, and RUNOPF_W_RES.0001 function mpc = add_userfcn(mpc, stage, fcn, args, allow_multiple) 0002 %ADD_USERFCN Appends a userfcn to the list to be called for a case. 0003 % 0004 % MPC = ADD_USERFCN(MPC, STAGE, FCN) 0005 % MPC = ADD_USERFCN(MPC, STAGE, FCN, ARGS) 0006 % MPC = ADD_USERFCN(MPC, STAGE, FCN, ARGS, ALLOW_MULTIPLE) 0007 % 0008 % A userfcn is a callback function that can be called automatically by 0009 % MATPOWER at one of various stages in a simulation. 0010 % 0011 % MPC : the case struct 0012 % STAGE : the name of the stage at which this function should be 0013 % called: ext2int, formulation, int2ext, printpf 0014 % FCN : the name of the userfcn 0015 % ARGS : (optional) the value to be passed as an argument to the 0016 % userfcn (typically a struct) 0017 % ALLOW_MULTIPLE : (optional) if TRUE, allows the same function to 0018 % be added more than once. 0019 % 0020 % Currently there are 5 different callback stages defined. Each stage has 0021 % a name, and by convention, the name of a user-defined callback function 0022 % ends with the name of the stage. The following is a description of each 0023 % stage, when it is called and the input and output arguments which vary 0024 % depending on the stage. The reserves example (see RUNOPF_W_RES) is used 0025 % to illustrate how these callback userfcns might be used. 0026 % 0027 % 1. ext2int 0028 % 0029 % Called from EXT2INT immediately after the case is converted from 0030 % external to internal indexing. Inputs are a MATPOWER case struct (MPC), 0031 % freshly converted to internal indexing and any (optional) ARGS value 0032 % supplied via ADD_USERFCN. Output is the (presumably updated) MPC. This is 0033 % typically used to reorder any input arguments that may be needed in 0034 % internal ordering by the formulation stage. 0035 % 0036 % E.g. mpc = userfcn_reserves_ext2int(mpc, args) 0037 % 0038 % 2. formulation 0039 % 0040 % Called from OPF after the OPF Model (OM) object has been initialized 0041 % with the standard OPF formulation, but before calling the solver. Inputs 0042 % are the OM object and any (optional) ARGS supplied via ADD_USERFCN. 0043 % Output is the OM object. This is the ideal place to add any additional 0044 % vars, constraints or costs to the OPF formulation. 0045 % 0046 % E.g. om = userfcn_reserves_formulation(om, args) 0047 % 0048 % 3. int2ext 0049 % 0050 % Called from INT2EXT immediately before the resulting case is converted 0051 % from internal back to external indexing. Inputs are the RESULTS struct 0052 % and any (optional) ARGS supplied via ADD_USERFCN. Output is the RESULTS 0053 % struct. This is typically used to convert any results to external 0054 % indexing and populate any corresponding fields in the RESULTS struct. 0055 % 0056 % E.g. results = userfcn_reserves_int2ext(results, args) 0057 % 0058 % 4. printpf 0059 % 0060 % Called from PRINTPF after the pretty-printing of the standard OPF 0061 % output. Inputs are the RESULTS struct, the file descriptor to write to, 0062 % a MATPOWER options struct, and any (optional) ARGS supplied via 0063 % ADD_USERFCN. Output is the RESULTS struct. This is typically used for 0064 % any additional pretty-printing of results. 0065 % 0066 % E.g. results = userfcn_reserves_printpf(results, fd, mpopt, args) 0067 % 0068 % 5. savecase 0069 % 0070 % Called from SAVECASE when saving a case struct to an M-file after 0071 % printing all of the other data to the file. Inputs are the case struct, 0072 % the file descriptor to write to, the variable prefix (typically 'mpc.') 0073 % and any (optional) ARGS supplied via ADD_USERFCN. Output is the case 0074 % struct. This is typically used to write any non-standard case struct 0075 % fields to the case file. 0076 % 0077 % E.g. mpc = userfcn_reserves_printpf(mpc, fd, prefix, args) 0078 % 0079 % See also RUN_USERFCN, REMOVE_USERFCN, TOGGLE_RESERVES, TOGGLE_IFLIMS, 0080 % TOGGLE_DCLINE, TOGGLE_SOFTLIMS, and RUNOPF_W_RES. 0081 0082 % MATPOWER 0083 % $Id: add_userfcn.m 2429 2014-11-18 21:37:33Z ray $ 0084 % by Ray Zimmerman, PSERC Cornell 0085 % Copyright (c) 2009-2010 by Power System Engineering Research Center (PSERC) 0086 % 0087 % This file is part of MATPOWER. 0088 % See http://www.pserc.cornell.edu/matpower/ for more info. 0089 % 0090 % MATPOWER is free software: you can redistribute it and/or modify 0091 % it under the terms of the GNU General Public License as published 0092 % by the Free Software Foundation, either version 3 of the License, 0093 % or (at your option) any later version. 0094 % 0095 % MATPOWER is distributed in the hope that it will be useful, 0096 % but WITHOUT ANY WARRANTY; without even the implied warranty of 0097 % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 0098 % GNU General Public License for more details. 0099 % 0100 % You should have received a copy of the GNU General Public License 0101 % along with MATPOWER. If not, see <http://www.gnu.org/licenses/>. 0102 % 0103 % Additional permission under GNU GPL version 3 section 7 0104 % 0105 % If you modify MATPOWER, or any covered work, to interface with 0106 % other modules (such as MATLAB code and MEX-files) available in a 0107 % MATLAB(R) or comparable environment containing parts covered 0108 % under other licensing terms, the licensors of MATPOWER grant 0109 % you additional permission to convey the resulting work. 0110 0111 if nargin < 5 0112 allow_multiple = 0; 0113 if nargin < 4 0114 args = []; 0115 end 0116 end 0117 switch stage 0118 case {'ext2int', 'formulation', 'int2ext', 'printpf', 'savecase'} 0119 %% ok 0120 otherwise 0121 error('add_userfcn : ''%s'' is not the name of a valid callback stage\n', stage); 0122 end 0123 0124 n = 1; 0125 if isfield(mpc, 'userfcn') 0126 if isfield(mpc.userfcn, stage) 0127 n = length(mpc.userfcn.(stage)) + 1; 0128 if ~allow_multiple 0129 if have_fcn('octave') 0130 fcn_info = functions(fcn); 0131 for k = 1:n-1 0132 cb_info = functions(mpc.userfcn.(stage)(k).fcn); 0133 if strcmp(cb_info.function, fcn_info.function) 0134 error('add_userfcn: the function ''%s'' has already been added', func2str(fcn)); 0135 end 0136 end 0137 else 0138 for k = 1:n-1 0139 if isequal(mpc.userfcn.(stage)(k).fcn, fcn) 0140 error('add_userfcn: the function ''%s'' has already been added', func2str(fcn)); 0141 end 0142 end 0143 end 0144 end 0145 end 0146 end 0147 0148 mpc.userfcn.(stage)(n).fcn = fcn; 0149 if ~isempty(args) 0150 mpc.userfcn.(stage)(n).args = args; 0151 end