MATPOWER solves power flow and optimal power flow in MATLAB or Octave

A simulation package, not an analysis platform

MATPOWER is a package of M-files for solving power flow, continuation power flow and optimal power flow problems using MATLAB or Octave. The stated purpose is narrow and worth keeping in view. It is intended as a simulation tool for researchers and educators that is easy to use and modify, and the design goal is to give the best performance possible while keeping the code simple to understand and modify. Those two goals sit in mild tension, and MATPOWER resolves it by being a library of functions you call from a prompt or a script rather than a system you deploy. There is no server, no database and no interface to speak of. The whole artefact is the directory of M-files and the data files that describe test cases, and the intended workflow is that you load a case, change it, run a solver, and read the results. That makes it a very different proposition from a commercial power system analysis suite, and for its stated audience that is a feature rather than a gap.

Two ways to get it, and the Extras difference

There are two distributions and the difference between them matters more than it first appears. The versioned release is downloaded as a ZIP file from the MATPOWER website, and the documentation notes that this does include the MATPOWER Extras. The current development version comes from the master branch on GitHub, and it includes new features and bug fixes added since the last versioned release, but it does not include the MATPOWER Extras. That asymmetry is easy to miss and it catches people out, because the two routes look equivalent and are not. The development version is also what the project says the master branch should always contain, described as a stable version, and it is the route to take if you want to keep updating with a simple git pull or if you want to help with testing or development. The documentation points to CONTRIBUTING.md for information on how to get a local copy of your own MATPOWER fork if you want to contribute code or modifications.

Installing with the installer script, then verifying

Installation requires familiarity with the basic operation of MATLAB or Octave, and the process was simplified with an install script following version 6.0. The steps are short. You get a copy of MATPOWER as a directory of your choice, and the documentation recommends keeping the files in that directory separate from your own code because the files in it should not need to be modified. Then you open MATLAB or Octave, change to that directory, and run the installer, which follows the directions to add the required directories to your MATLAB or Octave path.

            install_matpower

If you chose not to have the installer run the test suite during that step, you can verify the installation afterwards by typing.

            test_matpower

That check matters more than it appears. A MATLAB or Octave path that is not quite right produces function-not-found errors deep inside a solver rather than at install time, and a quick test run converts a confusing debugging session into a clear pass or fail. The documentation also notes that this step is skipped for the Open in MATLAB Online option.

Running a Newton power flow on the 9-bus case

The first example is a plain Newton power flow on the 9-bus system specified in the file case9.m, with the default algorithm options, at the MATLAB or Octave prompt.

runpf('case9')

The second example shows the pattern you will use constantly, which is to load a case into a struct, modify it, and pass the modified struct to a solver. It loads the 30-bus system data from case30.m, increases its real power demand at bus 2 to 30 MW, and runs an AC optimal power flow with default options.

define_constants;
mpc = loadcase('case30');
mpc.bus(2, PD) = 30;
runopf(mpc);

The define_constants call at the start is the piece to internalise. MATPOWER uses integer column constants such as PD to refer to positions in the bus, gen and branch matrices, and define_constants is what puts those names into your workspace. Once it has run, the case struct is a normal MATLAB struct with named fields, so mpc.bus(2, PD) reads as changing the real power demand column of the second bus, and the solver sees an ordinary struct that you could equally have built by hand. The example files in the repository include examples/convert_1p_to_3p_ex1.mlx and examples/cpf_example.m, the latter being a continuation power flow example.

Reading results through the results struct

By default the results of a simulation are pretty-printed to the screen, but the solution can also be returned in a results struct, and that is the interface you want for anything beyond reading a report. The documentation shows how simple it is after running a DC OPF on the 118-bus system in case118.m to reach the final objective function value, the real power output of generator 6, and the power flow in branch 51.

results = rundcopf('case118');
final_objective = results.f;
gen6_output     = results.gen(6, PG);
branch51_flow   = results.branch(51, PF);

The structure is consistent across solvers, so a script that reads results.f after an OPF and the same script after a power flow both work. That consistency is the practical reason to route your analysis through the struct rather than parsing printed output. For anything the struct does not expose, the built-in help documentation for the individual functions is the reference to reach for, with help runpf, help runopf, help mpoption and help caseformat given as examples, and the choice of algorithm and options is driven through mpoption.

System requirements and the MP-Core split

The requirements are stated in two tiers, and the split matters. For all features, including those based on the new MP-Core, you need MATLAB version 9.0 (R2016a) or later, or GNU Octave version 6.2 or later. Legacy features only, from 7.1 and earlier, are also available on MATLAB version 7.9 (R2009b) or later, or GNU Octave version 4 or later. In other words, a decade-old MATLAB installation can still run the older feature set, but nothing that depends on MP-Core, which is the newer architecture inside the package. The practical consequence is that an old MATLAB licence is not a reason to abandon MATPOWER, but it is a reason to check which feature set you can actually reach. The other environment factor is the container, since MATPOWER is also available on Docker Hub as the pre-packaged image tagged matpower/matpower, providing a Linux environment with Octave, MATPOWER and the MATPOWER Extras pre-installed, with images published for both versioned releases and development versions. That image is the fastest way to get a working environment without touching a local MATLAB install.

What sits in the distribution

The repository layout shows how much more than a solver is included. Alongside the top level install_matpower.m and matpower_project_startup.m there is a data directory holding the case files, a lib directory, a docs directory, an examples directory and a resources directory. There are also three separate sub-packages that live in the same tree. most/ is the MOST manual, documented as a User's Manual at most/docs/MOST-manual.pdf. mp-opt-model/ is the MP-Opt-Model manual at mp-opt-model/docs/MP-Opt-Model-manual.pdf. mips/ is the MIPS manual at mips/docs/MIPS-manual.pdf. A fourth, mptest/, carries its own README at mptest/README.md and functions as the test harness behind the test_matpower call. The documentation is unusually well organised for a package of this kind, with the User's Manuals available as PDF files in the distribution as well as online, current and past versions of the manuals also online, and a MATPOWER documentation website. There is a CHANGES.md, an AUTHORS file, a CITATION file and a matpower.prj project file, so the package is set up for citation and for use in a MATLAB project workspace.

Editorial conclusion

Adopt MATPOWER if you teach power systems, study OPF behaviour, or need a reference implementation of Newton power flow you can read and modify in MATLAB or Octave without a licence fee for Octave. Do not adopt it as an operational tool for a live network, since the package is explicitly a simulation tool, and do not expect a data pipeline, a UI or a service interface, because the whole deliverable is a set of M-files you call from a prompt. Verify two things before you build a course or study plan on it: that your MATLAB or Octave version meets the requirement for the features you intend to use, since all features including those based on MP-Core need MATLAB 9.0 (R2016a) or later or Octave 6.2 or later, and whether you want the versioned release with the MATPOWER Extras or the development branch, which does not include them. The practical first step is to run install_matpower from the unpacked directory and let it run the test suite, then run runpf('case9') to see a solved case.

Frequently asked questions

Official sources

1. Issues
2. MATPOWER/matpower on GitHub
3. Project website
4. README
5. Releases