Module add_userfcn

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

A userfcn is a callback function that can be called automatically by PYPOWER at one of various stages in a simulation.

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 PYPOWER case dict (ppc), freshly converted to internal indexing and any (optional) args value supplied via add_userfcn. Output is the (presumably updated) ppc. This is typically used to reorder any input arguments that may be needed in internal ordering by the formulation stage.

   E.g. ppc = userfcn_reserves_ext2int(ppc, 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 dict and any (optional) args supplied via add_userfcn. Output is the results dict. This is typically used to convert any results to external indexing and populate any corresponding fields in the results dict.

   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 dict, the file descriptor to write to, a PYPOWER options dict, and any (optional) args supplied via add_userfcn. Output is the results dict. This is typically used for any additional pretty-printing of results.

   E.g. results = userfcn_reserves_printpf(results, fd, ppopt, args)

5. 'savecase'

   Called from savecase when saving a case dict to a Python file after printing all of the other data to the file. Inputs are the case dict, the file descriptor to write to, the variable prefix (typically 'ppc') and any (optional) args supplied via add_userfcn. Output is the case dict. This is typically used to write any non-standard case dict fields to the case file.

   E.g. ppc = userfcn_reserves_printpf(ppc, fd, prefix, args)

Parameters:

• ppc - the case dict
• 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
• allow_multiple - (optional) if True, allows the same function to be added more than once.