A Power System Simulation Package for MATLAB and Octave

• MATPOWER Website - https://matpower.org
• MATPOWER GitHub Project - https://github.com/MATPOWER/matpower

MATPOWER is a package of M-files for solving power flow, continuation
power flow and optimal power flow problems using MATLAB or Octave. It
is intended as a simulation tool for researchers and educators that is
easy to use and modify. MATPOWER is designed to give the best
performance possible while keeping the code simple to understand and
modify.

MATPOWER releases can be downloaded from the MATPOWER website,
and the latest stable and work-in-progress versions can always be
downloaded or cloned from the MATPOWER GitHub project. The
master branch should always contain a stable version.

System Requirements

For all features, including those based on the new MP-Core:

• 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

Getting MATPOWER

You can either download an official versioned release or you can obtain
the current development version, which
we also attempt to keep stable enough for everyday use. The development
version includes new features and bug fixes added since the last
versioned release.

Versioned Releases

Download the ZIP file of the latest official versioned release from the
MATPOWER website.
Note: This does include the MATPOWER Extras.

Current Development Version

There are also two options for obtaining the most recent development version
of MATPOWER from the master branch on GitHub.
Note: This does not include the MATPOWER Extras.

1. Clone the MATPOWER repository from GitHub.
   Use this option if you want to be able to easily update to the current
   development release, with the latest bug fixes and new features, using a
   simple git pull command, or if you want to help with testing or
   or development. This requires that you have a Git client (GUI
   or command-line) installed.

   • From the command line:
     • git clone https://github.com/MATPOWER/matpower.git
   • Or, from the MATPOWER GitHub repository page:
     • Click the green Clone or download button, then Open in Desktop.

2. Download a ZIP file of the MATPOWER repository from GitHub.
   Use this option if you need features or fixes introduced since
   the latest versioned release, but you do not have access to or
   are not ready to begin using Git (but don't be afraid to
   give Git a try).

   • Go to the MATPOWER GitHub repository page.
   • Click the green Clone or download button, then Download ZIP.

See CONTRIBUTING.md for information on how to get a local copy
of your own MATPOWER fork, if you are interesting in contributing
your own code or modifications.

MATPOWER Docker Image

MATPOWER is also available on Docker Hub as the pre-packaged
Docker image tagged matpower/matpower, providing a Linux
environment with Octave, MATPOWER, and the MATPOWER Extras
pre-installed. See the MATPOWER-Docker page for more details.

Docker images are provided for both versioned releases and
development versions.

Installation

Installation and use of MATPOWER requires familiarity with the basic
operation of MATLAB or Octave. Make sure you follow the installation
instructions for the version of MATPOWER you are installing. The process
was simplified with an install script following version 6.0.

1. Get a copy of MATPOWER as described above. Clone the repository
   or download and extract the ZIP file of the MATPOWER distribution
   and place the resulting directory in the location of your choice
   and call it anything you like. We will use <MATPOWER> as a
   placeholder to denote the path to this directory (the one
   containing install_matpower.m). The files in <MATPOWER> should
   not need to be modified, so it is recommended that they be kept
   separate from your own code.

2. Run the installer.

   • Open MATLAB or Octave and change to the <MATPOWER> directory.

   • Run the installer and follow the directions to add the
     required directories to your MATLAB or Octave path, by typing:

       install_matpower
     

3. That's it. There is no step 3.

   • But, if you chose not to have the installer run the test suite for
     you in step 2, you can run it now to verify that MATPOWER is
     installed and functioning properly, by typing:

       test_matpower
     

Running MATPOWER

To run a simple 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, type:

runpf('case9')

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, type:

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

By default, the results of the simulation are pretty-printed to the
screen, but the solution can also be optionally returned in a results
struct. 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.

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

For additional info, see the MATPOWER User's Manual, the on-line
function reference, or the built-in help documentation for the various
MATPOWER functions. For example:

help runpf
help runopf
help mpoption
help caseformat

Documentation

There are a number of sources of documentation for MATPOWER

User's Manuals

The User's Manuals are available as PDF files in the MATPOWER distribution
as well as online.

• MATPOWER User's Manual -- docs/MATPOWER-manual.pdf
• MOST User's Manual -- most/docs/MOST-manual.pdf
• MP-Opt-User's Manual -- mp-opt-model/docs/MP-Opt-Model-manual.pdf
• MIPS Manual -- mips/docs/MIPS-manual.pdf
• MP-Test README -- mptest/README.md

Current and past versions of the manuals are also available online at:

• https://matpower.org/doc/manuals

MATPOWER Documentation website

The new MATPOWER Documentation site is intended to be the home for all
future MATPOWER documentation. It is very much a work-in-progress and
currently contains only the new:

• MATPOWER Developer's Manual

As new documentation is written and legacy manuals are rewritten, they
will be found here in HTML and PDF formats. The site is generated by
Sphinx and the content is written in reStructuredText (reST) format.

MATPOWER Online Function Reference

Built-in Help

Each M-file has its own documentation which can be accessed by typing at
the MATLAB/Octave prompt:

help <name of M-file>

Documentation for the case data file format can be found by typing:

help caseformat

If something is still unclear after checking the manual and the help,
the source code is the documentation. 😉

Changes

Changes to MATPOWER in each released version are summarized in the
release notes, found in docs/relnotes and in
Appendix H of the MATPOWER User's Manual. A complete, detailed
change log, even for unreleased versions, is available in the
CHANGES.md file.

Contributing

Please see our contributing guidelines for details on how to
contribute to the project or report issues.

Sponsoring the MATPOWER Project

If you have found MATPOWER to be valuable, please consider supporting
the project by becoming a sponsor.
MATPOWER development and support require significant resources. Any
contributions from the community or other sponsors free us to focus on
that support and the development of valuable new features.

Publications and Tech Notes

1. R. D. Zimmerman, C. E. Murillo-Sanchez, and R. J. Thomas,
   "MATPOWER: Steady-State Operations, Planning and Analysis Tools
   for Power Systems Research and Education," Power Systems, IEEE
   Transactions on, vol. 26, no. 1, pp. 12–19, Feb. 2011.
   doi: 10.1109/TPWRS.2010.2051168.

2. R. D. Zimmerman, C. E. Murillo-Sanchez, and R. J. Thomas,
   "MATPOWER's Extensible Optimal Power Flow Architecture,"
   Power and Energy Society General Meeting, 2009 IEEE, pp. 1-7,
   July 26-30 2009.
   doi: 10.1109/PES.2009.5275967.

   • slides of presentation

3. H. Wang, C. E. Murillo-Sánchez, R. D. Zimmerman, R. J. Thomas,
   "On Computational Issues of Market-Based Optimal Power Flow,"
   Power Systems, IEEE Transactions on, vol. 22, no. 3,
   pp. 1185-1193, Aug. 2007.
   doi: 10.1109/TPWRS.2007.901301.

4. C. E. Murillo-Sanchez, R. D. Zimmerman, C. L. Anderson, and
   R. J. Thomas, "Secure Planning and Operations of Systems with
   Stochastic Sources, Energy Storage and Active Demand,"
   Smart Grid, IEEE Transactions on, vol. 4, no. 4, pp. 2220–2229,
   Dec. 2013.
   doi: 10.1109/TSG.2013.2281001.

5. A. J. Lamadrid, D. Munoz-Alvarez, C. E. Murillo-Sanchez,
   R. D. Zimmerman, H. D. Shin and R. J. Thomas, "Using the MATPOWER
   Optimal Scheduling Tool to Test Power System Operation Methodologies
   Under Uncertainty," Sustainable Energy, IEEE Transactions on,
   vol. 10, no. 3, pp. 1280-1289, July 2019.
   doi: 10.1109/TSTE.2018.2865454.

6. R. D. Zimmerman, "Uniform Price Auctions and Optimal
   Power Flow," MATPOWER Technical Note 1, February 2010.
   Available: https://matpower.org/docs/TN1-OPF-Auctions.pdf
   doi: 10.5281/zenodo.3237850.

7. R. D. Zimmerman, "AC Power Flows, Generalized OPF Costs
   and their Derivatives using Complex Matrix Notation,"
   MATPOWER Technical Note 2, February 2010.
   Available:
   https://matpower.org/docs/TN2-OPF-Derivatives.pdf
   doi: 10.5281/zenodo.3237866.

8. B. Sereeter and R. D. Zimmerman, "Addendum to AC Power Flows and
   their Derivatives using Complex Matrix Notation: Nodal Current
   Balance," MATPOWER Technical Note 3, April 2018.
   Available: https://matpower.org/docs/TN3-More-OPF-Derivatives.pdf
   doi: 10.5281/zenodo.3237900.

9. B. Sereeter and R. D. Zimmerman, "AC Power Flows, Generalized
   OPF Costs and their Derivatives using Complex Matrix Notation
   and Cartesian Coordinate Voltages," MATPOWER Technical
   Note 4, April 2018.
   Available:
   https://matpower.org/docs/TN4-OPF-Derivatives-Cartesian.pdf
   doi: 10.5281/zenodo.3237909.

Citing MATPOWER

We request that publications derived from the use of MATPOWER, or the
included data files, explicitly acknowledge that fact by citing the
appropriate paper(s) and the software itself.

Papers

All publications derived from the use of MATPOWER, or the included data
files, should cite the 2011 MATPOWER paper:

R. D. Zimmerman, C. E. Murillo-Sanchez, and R. J. Thomas, "MATPOWER:
Steady-State Operations, Planning and Analysis Tools for Power Systems
Research and Education," Power Systems, IEEE Transactions on, vol. 26,
no. 1, pp. 12-19, Feb. 2011.
doi: 10.1109/TPWRS.2010.2051168

Publications derived from the use of the MATPOWER Optimal Scheduling
Tool (MOST) should cite the 2013 MOST paper, in addition to the
2011 MATPOWER paper above.

C. E. Murillo-Sanchez, R. D. Zimmerman, C. L. Anderson, and R. J. Thomas,
"Secure Planning and Operations of Systems with Stochastic Sources,
Energy Storage and Active Demand," Smart Grid, IEEE Transactions on,
vol. 4, no. 4, pp. 2220-2229, Dec. 2013.
doi: 10.1109/TSG.2013.2281001

Work making specific reference to the MATPOWER Interior Point Solver
(MIPS) should also cite:

H. Wang, C. E. Murillo-Sánchez, R. D. Zimmerman, R. J. Thomas, "On
Computational Issues of Market-Based Optimal Power Flow," Power Systems,
IEEE Transactions on, vol. 22, no. 3, pp. 1185-1193, Aug. 2007.
doi: 10.1109/TPWRS.2007.901301

NOTE: Some of the case files included with MATPOWER request the citation
of additional publications. This includes the ACTIVSg, PEGASE, and RTE
cases. Details are available in the help text at the top of the
corresponding case files.

Software

For the sake of reproducibility of research results, it is best to cite
the specific version of the software used, with the version-specfic DOI.
For example, for version 8.0 of MATPOWER, use:

R. D. Zimmerman, C. E. Murillo-Sanchez (2024). MATPOWER (Version 8.0)
[Software]. Available: https://matpower.org
doi: 10.5281/zenodo.11212330

To cite the MATPOWER software generally, without reference to a specific
version, use the following citation and DOI, with <YEAR> replaced by the
year of the most recent release:

R. D. Zimmerman, C. E. Murillo-Sanchez (<YEAR>). MATPOWER
[Software]. Available: https://matpower.org
doi: 10.5281/zenodo.3236535

A list of versions with release dates and version-specific DOI's can be
found via the general DOI at https://doi.org/10.5281/zenodo.3236535.

User's Manuals

The MATPOWER, MIPS and MOST User's Manuals should also be cited
explicitly in work that refers to or is derived from their content. As
with the software, the citation and DOI can be version-specific or
general, as appropriate. For version 8.0 of the MATPOWER User's Manual,
use:

R. D. Zimmerman, C. E. Murillo-Sanchez. MATPOWER User's Manual,
Version 8.0. 2024.
[Online]. Available: https://matpower.org/docs/MATPOWER-manual-8.0.pdf
doi: 10.5281/zenodo.11212313

For a version non-specific citation, use the following citation and DOI,
with <YEAR> replaced by the year of the most recent release:

R. D. Zimmerman, C. E. Murillo-Sanchez. MATPOWER User's Manual. <YEAR>.
[Online]. Available: https://matpower.org/docs/MATPOWER-manual.pdf
doi: 10.5281/zenodo.3236519

A list of versions of the User's Manual with release dates and
version-specific DOI's can be found via the general DOI at
https://doi.org/10.5281/zenodo.3236519.

For information on citing the MIPS or MOST User's Manuals, please see
the mips/CITATION and most/CITATION files, respectively.

Recommendation

In the interest of facilitating research reproducibility and thereby
increasing the value of your MATPOWER-related research publications, we
strongly encourage you to also publish, whenever possible, all of the
code and data required to generate the results you are publishing.
Zenodo/GitHub and IEEE DataPort are two of many available
options.

E-mail Lists

There are two e-mail lists available to serve the MATPOWER community:

• Discussion List (MATPOWER-L) – to facilitate discussion
  among MATPOWER users and provide a forum for help with MATPOWER
  related questions

• Developer List (MATPOWER-DEV-L) – to provide a forum
  for discussion among MATPOWER users and developers related to the
  development of the MATPOWER software or proposed contributions

For details see the Mailing Lists section of the
MATPOWER website.

Please select the most appropriate list for your post and do not
cross-post to both Discussion and Developer lists. Bug reports,
software patches, proposed enhancements, etc. should be submitted to
the issue tracker on GitHub.

Optional Packages

There are numerous optional packages to enhance the performance of
MATPOWER that must be installed separately. The terms of use and
license agreements vary. Some are free of charge for all to use,
others are only free for academic use, and others may require a
commercial license. Please see Appendix G of the MATPOWER User's
Manual for details.

License and Terms of Use

MATPOWER is distributed as open-source under the 3-clause BSD license.