How to Create an Extension
This guide demonstrates how to create a MATPOWER extension to package up your new functionality and make it accessible to a MATPOWER end user.
In general, new or modified functionality takes the form of additional classes that inherit from or override functionality in existing classes, or classes that are entirely new. The Customizing MATPOWER section in the MATPOWER Developer’s Manual describes how MATPOWER selects the classes to use for a given run and some mechanisms to make changes to the defaults. In particular, to change the element classes associated with a particular container (e.g. data model, network model, etc.) MATPOWER uses element class modifiers which are summarized in the Element Classes section and the Element Class Modifiers table.
In this guide, we will use the example of adding a new network element, namely the model of a DC line used by legacy MATPOWER versions. The classes that implement this functionality are described in How to Create a New Element Type. Here we show how to package these into a MATPOWER extension.
This extension adds a new legacy_dcline element for power flow (PF), continuation power flow (CPF), and optimal power flow (OPF) problems. For PF and OPF, it includes both DC and AC formulations, and for the AC formulations both cartesian and polar voltage representations are implemented. Listing 20 shows the code for this extension. As with all MATPOWER extensions, it inherits from mp.extension. In this example, no changes are required for the task or container classes, so only the methods with names ending in _element_classes are overridden.
For each model layer, it adds a single element class. For the data model element, that class depends on the task. For the network model element, it depends on the formulation, and for the math model element, it depends on both.
1classdef xt_legacy_dcline < mp.extension
2 methods
3 function dmc_elements = dmc_element_classes(obj, dmc_class, fmt, mpopt)
4 switch fmt
5 case 'mpc2'
6 dmc_elements = { @mp.dmce_legacy_dcline_mpc2 };
7 otherwise
8 dmc_elements = {};
9 end
10 end
11
12 function dm_elements = dm_element_classes(obj, dm_class, task_tag, mpopt)
13 switch task_tag
14 case {'PF', 'CPF'}
15 dm_elements = { @mp.dme_legacy_dcline };
16 case 'OPF'
17 dm_elements = { @mp.dme_legacy_dcline_opf };
18 otherwise
19 dm_elements = {};
20 end
21 end
22
23 function nm_elements = nm_element_classes(obj, nm_class, task_tag, mpopt)
24 switch task_tag
25 case {'PF', 'CPF'}
26 v_cartesian = mpopt.pf.v_cartesian;
27 case {'OPF'}
28 v_cartesian = mpopt.opf.v_cartesian;
29 end
30 switch upper(mpopt.model)
31 case 'AC'
32 if v_cartesian
33 nm_elements = { @mp.nme_legacy_dcline_acc };
34 else
35 nm_elements = { @mp.nme_legacy_dcline_acp };
36 end
37 case 'DC'
38 nm_elements = { @mp.nme_legacy_dcline_dc };
39 otherwise
40 nm_elements = {};
41 end
42 end
43
44 function mm_elements = mm_element_classes(obj, mm_class, task_tag, mpopt)
45 switch task_tag
46 case {'PF', 'CPF'}
47 switch upper(mpopt.model)
48 case 'AC'
49 mm_elements = { @mp.mme_legacy_dcline_pf_ac };
50 case 'DC'
51 mm_elements = { @mp.mme_legacy_dcline_pf_dc };
52 end
53 case {'OPF'}
54 switch upper(mpopt.model)
55 case 'AC'
56 mm_elements = { @mp.mme_legacy_dcline_opf_ac };
57 case 'DC'
58 mm_elements = { @mp.mme_legacy_dcline_opf_dc };
59 end
60 otherwise
61 dm_elements = {};
62 end
63 end
64 end %% methods
65end %% classdef
See lib/t/+mp/xt_legacy_dcline.m for the complete, documented mp.dmce_legacy_dcline_mpc2 source.
Using the Extension
To make use of the extension, simply pass it, as an optional argument, immediately following 'mpx' to run_pf(), run_cpf(), or run_opf(), as follows.
>> mpopt = mpoption('verbose', 0);
>> run_opf('t_case9_dcline', mpopt, 'mpx', mp.xt_legacy_dcline)
OPF succeeded in 0.27 seconds (0.23 setup + 0.04 solve)
Objective Function Value = 6518.89 $/hr
================================================================================
| System Summary |
================================================================================
elements on off total
--------------------- ------- ------- -------
Buses 9 - 9
Areas 1
Zones 1
Generators 3 - 3
Loads 3 - 3
Branches 9 - 9
Lines 9 - 9
Transformers 0 - 0
DC Lines 3 1 4
Total generation 319.4 MW 1.5 MVAr
Total max generation capacity 820.0 MW 900.0 MVAr
Total min generation capacity 110.0 MW -900.0 MVAr
Total load 315.0 MW 115.0 MVAr
Total branch losses 3.00 MW -124.10 MVAr
Total DC line losses 1.40 MW -10.59 MVAr
minimum maximum
----------------------------- -----------------------------
Bus voltage magnitude 1.066 p.u. @ bus 30 1.100 p.u. @ bus 1
Bus voltage angle -4.51 deg @ bus 5 4.11 deg @ bus 2
Lambda P (LMP active power) 14.99 $/MWh @ bus 6 24.48 $/MWh @ bus 9
Lambda Q (LMP reactive power) -0.62 $/MVArh @ bus 30 0.43 $/MVArh @ bus 7
================================================================================
| Bus Data |
================================================================================
Voltage Lambda (LMP)
Bus ID Status Mag(pu) Ang(deg) P($/MWh) Q($/MVAr-hr)
-------- ------ ------- -------- -------- ------------
1 1 1.100 0.000 15.954 0.000
2 1 1.100 4.107 24.035 0.000
30 1 1.066 2.277 15.047 -0.623
4 1 1.094 -2.470 15.967 0.298
5 1 1.078 -4.508 15.952 -0.000
6 1 1.085 -0.277 14.992 -0.600
7 1 1.081 -2.160 24.476 0.427
8 1 1.097 0.205 24.043 0.112
9 1 1.067 -4.470 24.476 -0.079
================================================================================
| Load Data |
================================================================================
Power Consumption
Load ID Bus ID Status P (MW) Q (MVAr)
-------- -------- ------ -------- --------
1 5 1 90.0 30.0
2 7 1 100.0 35.0
3 9 1 125.0 50.0
-------- --------
Total: 315.0 115.0
================================================================================
| Branch Data |
================================================================================
Branch From To From Bus Injection To Bus Injection
ID Bus ID Bus ID Status P (MW) Q (MVAr) P (MW) Q (MVAr)
-------- -------- -------- ------ -------- -------- -------- --------
1 1 4 1 90.00 14.19 -90.00 -10.24
2 4 5 1 47.54 1.31 -47.20 -18.11
3 5 6 1 -48.85 -12.48 49.68 -25.81
4 30 6 1 88.02 -32.65 -88.02 37.19
5 6 7 1 38.35 -11.39 -38.20 -11.87
6 7 8 1 -69.64 -23.13 70.01 8.58
7 8 2 1 -131.39 -0.99 131.39 9.95
8 8 9 1 61.37 -7.59 -60.34 -23.03
9 9 4 1 -51.06 -36.97 51.36 18.92
================================================================================
| DC Line Data |
================================================================================
DC Line From To Power Flow (MW) Loss Reactive Inj (MVAr)
ID Bus ID Bus ID Status From To (MW) From To
-------- -------- -------- ------ -------- -------- -------- -------- --------
1 30 4 1 10.00 8.90 1.10 -10.00 10.00
2 7 9 1 7.84 7.84 0.00 -0.00 -0.00
3 5 8 0 0.00 0.00 0.00 0.00 0.00
4 5 9 1 6.06 5.75 0.30 -0.59 -10.00
================================================================================
| Bus Constraints |
================================================================================
Voltage Magnitude Limits
Bus ID mu LB LB vm UB mu UB
-------- --------- ------- ------- ------- --------
1 - 0.900 1.100 1.100 566.231
2 - 0.900 1.100 1.100 197.010
================================================================================
| Generator Constraints |
================================================================================
Active Power Limits
Gen ID Bus ID mu LB LB pg UB mu UB
-------- -------- --------- ------- ------- ------- --------
1 1 9.046 90.00 90.00 250.00 -
2 30 - 10.00 98.02 270.00 0.047
Reactive Power Limits
Gen ID Bus ID mu LB LB qg UB mu UB
-------- -------- --------- ------- ------- ------- --------
2 30 0.623 -300.00 -22.65 300.00 -
================================================================================
| Branch Constraints (S in MVA) |
================================================================================
Branch From "From" End Limit "To" End To
ID Bus ID mu_sm_fr sm_fr sm_ub sm_to mu_sm_to Bus ID
-------- -------- --------- ------- ------- ------- --------- --------
5 6 2.762 40.00 40.00 40.00 7.375 7
================================================================================
| DC Line Constraints |
================================================================================
DC Line From To Active Power Flow (MW)
ID Bus ID Bus ID mu LB LB p_fr UB mu UB
-------- -------- -------- --------- ------- ------- ------- ---------
1 30 4 - 1.00 10.00 10.00 0.760