The primary functionality of Matpower is to solve power ﬂow and optimal power ﬂow (OPF) problems. This involves (1) preparing the input data deﬁning the all of the relevant power system parameters, (2) invoking the function to run the simulation and (3) viewing and accessing the results that are printed to the screen and/or saved in output data structures or ﬁles.
The input data for the case to be simulated are speciﬁed in a set of data matrices packaged as the ﬁelds of a Matlab struct, referred to as a “Matpower case” struct and conventionally denoted by the variable mpc. This struct is typically deﬁned in a case ﬁle, either a function M-ﬁle whose return value is the mpc struct or a MAT-ﬁle that deﬁnes a variable named mpc when loaded23 . The main simulation routines, whose names begin with run (e.g. runpf, runopf), accept either a ﬁle name or a Matpower case struct as an input.
Use loadcase to load the data from a case ﬁle into a struct if you want to make modiﬁcations to the data before passing it to the simulation.
See also savecase for writing a Matpower case struct to a case ﬁle.
The structure of the Matpower case data is described a bit further in Section 3.1 and the full details are documented in Appendix B and can be accessed at any time via the command help caseformat. The Matpower distribution also includes many example case ﬁles listed in Table D-18.
The solver is invoked by calling one of the main simulation functions, such as runpf or runopf, passing in a case ﬁle name or a case struct as the ﬁrst argument. For example, to run a simple Newton power ﬂow with default options on the 9-bus system deﬁned in case9.m, at the Matlab prompt, type:
If, on the other hand, you wanted to load the 30-bus system data from case30.m, increase its real power demand at bus 2 to 30 MW, then run an AC optimal power ﬂow with default options, this could be accomplished as follows:
The define_constants in the ﬁrst line is simply a convenience script that deﬁnes a number of variables to serve as named column indices for the data matrices. In this example, it allows us to access the “real power demand” column of the bus matrix using the name PD without having to remember that it is the 3rd column.
Other top-level simulation functions are available for running DC versions of power ﬂow and OPF, for running an OPF with the option for Matpower to shut down (decommit) expensive generators, etc. These functions are listed in Table D-2 in Appendix D.
By default, the results of the simulation are pretty-printed to the screen, displaying a system summary, bus data, branch data and, for the OPF, binding constraint information. The bus data includes the voltage, angle and total generation and load at each bus. It also includes nodal prices in the case of the OPF. The branch data shows the ﬂows and losses in each branch. These pretty-printed results can be saved to a ﬁle by providing a ﬁlename as the optional 3rd argument to the simulation function.
The solution is also stored in a results struct available as an optional return value from the simulation functions. This results struct is a superset of the Matpower case struct mpc, with additional columns added to some of the existing data ﬁelds and additional ﬁelds. The following example shows how simple it is, after running a DC OPF on the 118-bus system in case118.m, to access the ﬁnal objective function value, the real power output of generator 6 and the power ﬂow in branch 51.
Full documentation for the content of the results struct can be found in Sections 4.4 and 6.6.
Matpower has many options for selecting among the available solution algorithms, controlling the behavior of the algorithms and determining the details of the pretty-printed output. These options are passed to the simulation routines as a Matpower options struct. The ﬁelds of the struct have names that can be used to set the corresponding value via the mpoption function. Calling mpoption with no arguments returns the default options struct, the struct used if none is explicitly supplied. Calling it with a set of name and value pairs modiﬁes the default vector.
For example, the following code runs a power ﬂow on the 300-bus example in case300.m using the fast-decoupled (XB version) algorithm, with verbose printing of the algorithm progress, but suppressing all of the pretty-printed output.
To modify an existing options struct, for example, to turn the verbose option oﬀ and re-run with the remaining options unchanged, simply pass the existing options as the ﬁrst argument to mpoption.
See Appendix C or type:
for more information on Matpower’s options.