The primary functionality of Matpower is to solve power flow and optimal power flow (OPF) problems. This involves (1) preparing the input data defining 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 files.
The input data for the case to be simulated are specified in a set of data matrices packaged as the fields of a Matlab struct, referred to as a “Matpower case” struct and conventionally denoted by the variable mpc. This struct is typically defined in a case file, either a function M-file whose return value is the mpc struct or a MAT-file that defines a variable named mpc when loaded23 . The main simulation routines, whose names begin with run (e.g. runpf, runopf), accept either a file name or a Matpower case struct as an input.
Use loadcase to load the data from a case file into a struct if you want to make modifications to the data before passing it to the simulation.
See also savecase for writing a Matpower case struct to a case file.
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 files 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 file name or a case struct as the first argument. For example, to run a simple Newton power flow with default options on the 9-bus system defined 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 flow with default options, this could be accomplished as follows:
The define_constants in the first line is simply a convenience script that defines 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 flow 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 flows and losses in each branch. These pretty-printed results can be saved to a file by providing a filename 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 fields and additional fields. The following example shows how simple it is, after running a DC OPF on the 118-bus system in case118.m, to access the final objective function value, the real power output of generator 6 and the power flow 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 fields 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 modifies the default vector.
For example, the following code runs a power flow 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 off and re-run with the remaining options unchanged, simply pass the existing options as the first argument to mpoption.
See Appendix C or type:
for more information on Matpower’s options.