MATP WER
User’s Manual
Version 7.1
Ray D. Zimmerman Carlos E. Murillo-S´anchez
October 8, 2020
© 2010–2020 Power Systems Engineering Research Center (PSerc)
All Rights Reserved
Contents
1 Introduction 10
1.1 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.2 License and Terms of Use . . . . . . . . . . . . . . . . . . . . . . . . 11
1.3 Citing Matpower . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.4 Matpower Development . . . . . . . . . . . . . . . . . . . . . . . . 14
1.5 Sponsoring the Matpower Project . . . . . . . . . . . . . . . . . . . 14
2 Getting Started 15
2.1 System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.2 Getting Matpower . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.2.1 Versioned Releases . . . . . . . . . . . . . . . . . . . . . . . . 16
2.2.2 Current Development Version . . . . . . . . . . . . . . . . . . 16
2.2.3 Matpower Docker Image . . . . . . . . . . . . . . . . . . . . 17
2.3 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.4 Running a Simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.4.1 Preparing Case Input Data . . . . . . . . . . . . . . . . . . . . 20
2.4.2 Solving the Case . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.4.3 Accessing the Results . . . . . . . . . . . . . . . . . . . . . . . 22
2.4.4 Setting Options . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.5 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3 Modeling 25
3.1 Data Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.2 Branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.3 Generators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.4 Loads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.5 Shunt Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.6 Network Equations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.7 DC Modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
4 Power Flow 32
4.1 AC Power Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.1.1 Cartesian vs. Polar Coordinates for Voltage . . . . . . . . . . 34
4.1.2 Current vs. Power for Nodal Balance Equations . . . . . . . . 35
4.2 DC Power Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.3 Distribution Power Flow . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.3.1 Radial Power Flow . . . . . . . . . . . . . . . . . . . . . . . . 37
4.3.2 Current Summation Method . . . . . . . . . . . . . . . . . . . 38
4.3.3 Power Summation Method . . . . . . . . . . . . . . . . . . . . 39
4.3.4 Admittance Summation Method . . . . . . . . . . . . . . . . . 39
4.3.5 Handling PV Buses . . . . . . . . . . . . . . . . . . . . . . . . 41
4.4 runpf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
4.5 Linear Shift Factors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
5 Continuation Power Flow 48
5.1 Parameterization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
5.2 Predictor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
5.3 Corrector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
5.4 Step Length Control . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
5.5 Event Detection and Location . . . . . . . . . . . . . . . . . . . . . . 51
5.6 runcpf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
5.6.1 CPF Callback Functions . . . . . . . . . . . . . . . . . . . . . 55
5.6.2 CPF Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
6 Optimal Power Flow 61
6.1 Standard AC OPF . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
6.1.1 Cartesian vs. Polar Coordinates for Voltage . . . . . . . . . . 63
6.1.2 Current vs. Power for Nodal Balance Constraints . . . . . . . 63
6.2 Standard DC OPF . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
6.3 Extended OPF Formulation . . . . . . . . . . . . . . . . . . . . . . . 65
6.3.1 User-defined Variables . . . . . . . . . . . . . . . . . . . . . . 66
6.3.2 User-defined Constraints . . . . . . . . . . . . . . . . . . . . . 66
6.3.3 User-defined Costs . . . . . . . . . . . . . . . . . . . . . . . . 67
6.4 Standard Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
6.4.1 Piecewise Linear Costs . . . . . . . . . . . . . . . . . . . . . . 69
6.4.2 Dispatchable Loads . . . . . . . . . . . . . . . . . . . . . . . . 71
6.4.3 Generator Capability Curves . . . . . . . . . . . . . . . . . . . 73
6.4.4 Branch Angle Difference Limits . . . . . . . . . . . . . . . . . 73
6.5 Solvers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
6.6 runopf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
7 Extending the OPF 81
7.1 Direct Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
7.1.1 User-defined Variables . . . . . . . . . . . . . . . . . . . . . . 81
7.1.2 User-defined Constraints . . . . . . . . . . . . . . . . . . . . . 81
7.1.3 User-defined Costs . . . . . . . . . . . . . . . . . . . . . . . . 83
2
7.1.4 Additional Comments . . . . . . . . . . . . . . . . . . . . . . 84
7.2 Callback Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
7.2.1 User-defined Variables . . . . . . . . . . . . . . . . . . . . . . 85
7.2.2 User-defined Costs . . . . . . . . . . . . . . . . . . . . . . . . 85
7.2.3 User-defined Constraints . . . . . . . . . . . . . . . . . . . . . 86
7.3 Callback Stages and Example . . . . . . . . . . . . . . . . . . . . . . 87
7.3.1 ext2int Callback . . . . . . . . . . . . . . . . . . . . . . . . . 88
7.3.2 formulation Callback . . . . . . . . . . . . . . . . . . . . . . 89
7.3.3 int2ext Callback . . . . . . . . . . . . . . . . . . . . . . . . . 93
7.3.4 printpf Callback . . . . . . . . . . . . . . . . . . . . . . . . . 96
7.3.5 savecase Callback . . . . . . . . . . . . . . . . . . . . . . . . 98
7.4 Registering the Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . 100
7.5 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
7.6 Example Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
7.6.1 Fixed Zonal Reserves . . . . . . . . . . . . . . . . . . . . . . . 102
7.6.2 Interface Flow Limits . . . . . . . . . . . . . . . . . . . . . . . 104
7.6.3 DC Transmission Lines . . . . . . . . . . . . . . . . . . . . . . 105
7.6.4 OPF Soft Limits . . . . . . . . . . . . . . . . . . . . . . . . . 108
8 Unit De-commitment Algorithm 115
9 Miscellaneous Matpower Functions 117
9.1 Input/Output Functions . . . . . . . . . . . . . . . . . . . . . . . . . 117
9.1.1 loadcase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
9.1.2 savecase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
9.1.3 cdf2mpc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
9.1.4 psse2mpc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
9.1.5 save2psse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
9.2 System Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
9.2.1 case info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
9.2.2 compare case . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
9.2.3 find islands . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
9.2.4 get losses . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
9.2.5 margcost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
9.2.6 isload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
9.2.7 loadshed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
9.2.8 printpf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
9.2.9 total load . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
3
9.2.10 totcost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
9.3 Modifying a Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
9.3.1 extract islands . . . . . . . . . . . . . . . . . . . . . . . . . 122
9.3.2 load2disp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
9.3.3 modcost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
9.3.4 scale load . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
9.3.5 apply changes . . . . . . . . . . . . . . . . . . . . . . . . . . 124
9.3.6 savechgtab . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
9.4 Conversion between External and Internal Numbering . . . . . . . . . 128
9.4.1 ext2int, int2ext . . . . . . . . . . . . . . . . . . . . . . . . . 128
9.4.2 e2i data, i2e data . . . . . . . . . . . . . . . . . . . . . . . . 128
9.4.3 e2i field, i2e field . . . . . . . . . . . . . . . . . . . . . . 129
9.5 Forming Standard Power Systems Matrices . . . . . . . . . . . . . . . 130
9.5.1 makeB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
9.5.2 makeBdc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
9.5.3 makeJac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
9.5.4 makeLODF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
9.5.5 makePTDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
9.5.6 makeYbus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
9.6 Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
9.6.1 define constants . . . . . . . . . . . . . . . . . . . . . . . . 132
9.6.2 feval w path . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
9.6.3 have fcn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
9.6.4 mpopt2qpopt . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
9.6.5 mpver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
9.6.6 nested struct copy . . . . . . . . . . . . . . . . . . . . . . . 133
9.7 Private Feature Detection Functions . . . . . . . . . . . . . . . . . . . 133
9.7.1 have feature e4st . . . . . . . . . . . . . . . . . . . . . . . . 133
9.7.2 have feature minopf . . . . . . . . . . . . . . . . . . . . . . 133
9.7.3 have feature most . . . . . . . . . . . . . . . . . . . . . . . . 134
9.7.4 have feature pdipmopf . . . . . . . . . . . . . . . . . . . . . 134
9.7.5 have feature regexp split . . . . . . . . . . . . . . . . . . . 134
9.7.6 have feature scpdipmopf . . . . . . . . . . . . . . . . . . . . 134
9.7.7 have feature sdp pf . . . . . . . . . . . . . . . . . . . . . . . 134
9.7.8 have feature smartmarket . . . . . . . . . . . . . . . . . . . 134
9.7.9 have feature syngrid . . . . . . . . . . . . . . . . . . . . . . 134
9.7.10 have feature tralmopf . . . . . . . . . . . . . . . . . . . . . 135
4
