Home > matpower5.0 > add_userfcn.m

add_userfcn

PURPOSE ^

ADD_USERFCN Appends a userfcn to the list to be called for a case.

SYNOPSIS ^

function mpc = add_userfcn(mpc, stage, fcn, args, allow_multiple)

DESCRIPTION ^

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.

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SOURCE CODE ^

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

Generated on Mon 26-Jan-2015 15:21:31 by m2html © 2005