matpower-pip: A Python Package for Easy Access to MATPOWER Power System Simulation Package
This package is intended to make MATPOWER installable from PyPI
. We did not change anything from MATPOWER
package, instead, we used a copy of MATPOWER
(currently Version 8.0
) and wrapped it as python package
published on PyPI. Use this package with mypower
(the recommended way) or oct2py
to run MATPOWER
using octave
client. matlab.engine
is also supported. For the latest docs, read README on GitHub.
This project is also listed on related links on MATPOWER
official website. Please visit that site to find other useful resources.
For downloading MATPOWER
only (maybe you will run it using matlab.engine
or any other method, or simply want an easy MATPOWER
downloader):
pip install matpower
For callable matpower
via oct2py
(require octave on environment system PATH
). You can follow the oct2py instalation tutorial in mypower repository.
See notebooks/
for complete examples. All examples should be compatible with Google Colab.
If oct2py
or matlab.engine
is installed, matpower.start_instance
can be used to run octave
or MATLAB
with MATPOWER
path added. The default engine is octave
. You also can use mypower
for added functionality as shown in mypower tutorial
.
from matpower import start_instance
m = start_instance()
m.runpf()
from matpower import start_instance
m = start_instance()
mpc = m.eval('case9', verbose=False)
mpc = m.runpf(mpc)
from matpower import Matpower
with Matpower(engine='octave') as m: # run as context manager
mpc = m.eval('case9', verbose=False)
mpc = m.runpf(mpc)
print(m._engine is None) # engine cleanly terminated
from matpower import path_matpower
print(path_matpower) # matpower installation location
Since mpc = m.runopf()
will make mpc
contain unsupported <object opf_model>
, we can avoid it by requesting a maximum number of outputs using nout='max_nout'
in octave
.
from matpower import start_instance
m = start_instance()
mpc = m.loadcase('case9')
mpopt = m.mpoption('verbose', 2)
[baseMVA, bus, gen, gencost, branch, f, success, et] = m.runopf(mpc, mpopt, nout='max_nout')
Or we can remove unsupported objects.
from matpower import start_instance
m = start_instance()
mpc = m.loadcase('case9')
mpopt = m.mpoption('verbose', 2)
m.push("_mpopt", mpopt)
m.push("_mpc", mpc, verbose=False)
m.eval("_r1 = runopf(_mpc, _mpopt);", verbose=False)
# `_r1` containts unsupported `<object opf_model>`, needs to be removed first
m.eval(
"""
_r1.raw = rmfield(_r1.raw, 'task');
_r1 = rmfield(_r1, 'om');
"""
)
mpc = m.pull("_r1")
Alternatively, only select values that will be used on python using oct2py
.eval
method. Combine it with the use of ;
to avoid octave print output on running the command.
# import start_instance to start matpower instance
from matpower import start_instance
# start instance
m = start_instance()
m.eval(
"""
mpopt = mpoption('verbose', 2);
mpc = loadcase('case9');
_r1 = runopf(mpc, mpopt);
"""
)
# fech data to python (.eval is used because .pull is not working in acessing field)
r1_mpc = m.eval(
"struct("
" 'baseMVA', _r1.baseMVA, 'version', _r1.version, 'bus', _r1.bus, 'gen', _r1.gen,"
" 'branch', _r1.branch, 'gencost', _r1.gencost);"
)
# modify variable if necessary
[GEN_BUS, PG, QG, QMAX, QMIN, VG, MBASE, GEN_STATUS, PMAX, PMIN, MU_PMAX,
MU_PMIN, MU_QMAX, MU_QMIN, PC1, PC2, QC1MIN, QC1MAX, QC2MIN, QC2MAX,
RAMP_AGC, RAMP_10, RAMP_30, RAMP_Q, APF] = m.idx_gen(nout='max_nout')
gen_index = 2 # index of generator to be changed
gen_index_ = int(gen_index - 1) # -1 due to python indexing start from 0
PMAX_ = int(PMAX -1) # -1 due to python indexing start from 0
r1_mpc['gen'][gen_index_,PMAX_] = 110 # in this example, we modify PMAX to be 110
[PQ, PV, REF, NONE, BUS_I, BUS_TYPE, PD, QD, GS, BS,
BUS_AREA, VM, VA, BASE_KV, ZONE, VMAX, VMIN, LAM_P,
LAM_Q, MU_VMAX, MU_VMIN] = m.idx_bus(nout='max_nout')
bus_index = 7 # index of bus to be changed
bus_index_ = int(bus_index - 1) # -1 due to python indexing start from 0
PD_ = int(PD-1) # -1 due to python indexing start from 0
r1_mpc['bus'][bus_index_,int(PD-1)] = 80 # in this example, we modify PD to be 150
# push back value to octave client
m.push('mpc', r1_mpc) # push r1_mpc in python to mpc in octave
# test if we can retrive pushed value
mpc = m.pull('mpc')
# test if our pushed variable can be used
m.eval("_r1 = runopf(mpc, mpopt);")
matpower-pip
also support using matlab.engine
.
from matpower import start_instance
m = start_instance(engine='matlab') # specify using `matlab.engine` instead of `oct2py`
mpc = m.runpf('case5', nargout=0)
-
m.runopf()
will makempc
contain unsupported<object opf_model>
. See: MATPOWER/matpower#134 (comment)Impacted case:
_r1 = m.runopf(mpc)
Solution:
m.push('mpc', mpc) r1_mpc = m.eval( """ mpopt = mpoption('verbose', 2); _r1 = runopf(mpc, mpopt); """ "struct(" " 'baseMVA', _r1.baseMVA, 'version', _r1.version, 'bus', _r1.bus, 'gen', _r1.gen," " 'branch', _r1.branch, 'gencost', _r1.gencost);" )
This package maintains MATPOWER
version with an added version mark, i.e. MATPOWER 7.1
becomes 7.1.0.x.x.x
where the .x.x.x
comes from matpower-pip
versioning. The matpower-pip
versioning is not released on pypi
since matpower-pip
is restricted for development only (and development should use git instead).
conda
anddocker
installation that includes octave-cli installation.
- Muhammad Yasirroni - yasirroni
We do request that publications derived from the use of matpower-pip
explicitly acknowledge that fact by including all related MATPOWER publications and the following citation:
M. Yasirroni, Sarjiya, and L. M. Putranto, "matpower-pip: A Python Package for Easy Access to MATPOWER Power System Simulation Package," [Online]. Available: https://github.com/yasirroni/matpower-pip.
M. Yasirroni, Sarjiya, and L. M. Putranto, "matpower-pip". Zenodo, Jun. 13, 2024. doi: 10.5281/zenodo.11626845.
@misc{matpower-pip,
author = {Yasirroni, M. and Sarjiya and Putranto, L. M.},
title = {matpower-pip: A Python Package for Easy Access to MATPOWER Power System Simulation Package},
year = {2023},
howpublished = {\url{https://github.com/yasirroni/matpower-pip}},
}
@software{yasirroni_2024_11626845,
author = {Yasirroni, Muhammad and
Sarjiya, Sarjiya and
Putranto, Lesnanto Multa},
title = {matpower-pip},
month = jun,
year = 2024,
publisher = {Zenodo},
version = {8.0.0.2.1.8},
doi = {10.5281/zenodo.11626845},
url = {\url{https://doi.org/10.5281/zenodo.11626845}}
}
If a journal publication from the author appears soon should be cited instead.
See the CONTRIBUTING.md.
This repository was supported by the Faculty of Engineering, Universitas Gadjah Mada under the supervision of Mr. Sarjiya. If you use this package, we would be very glad if you cite any relevant publication under Mr. Sarjiya's name that can be found in the semantic scholar or IEEE in the meantime, since publication related to this repository is ongoing. This work is also partly motivated after I found out that oct2py
supports running octave
client from python
, but the only implementation for running MATPOWER
that I know is oct2pypower which requires docker
and is not newbie-friendly. Nevertheless, I would like to say thank you to all the people who have contributed to oct2py
, oct2pypower
, and more importantly MATPOWER
.