Skip to content

Commit

Permalink
Add How to Run a Three-Phase Power Flow to docs.
Browse files Browse the repository at this point in the history
  • Loading branch information
@rdzman
rdzman committed Feb 21, 2024
1 parent 72a0160 commit 87bb91b
Show file tree
Hide file tree
Showing 3 changed files with 274 additions and 0 deletions.
267 changes: 267 additions & 0 deletions docs/sphinx/source/howto/three-phase.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,267 @@
.. _howto_three_phase:

How to Run a Three-Phase Power Flow
===================================

This guide describes how to run a power flow on a three-phase, unbalanced model.
|MATPOWER| 8 includes the core functionality required to build out three-phase unbalanced modeling. It also includes a few simple prototype three-phase elements: buses, lines, generators, loads, and transformers and even a bus-link element used to connect three-phase and single-phase parts of a model.

.. note::

Keep in mind these are **prototype** elements. That means that the data formats used, etc. are not final and there are many additions, enhancements and changes planned for future versions. So don't count on future versions to be backward compatible with these prototypes.

The functionality is accessed through the |MATPOWER| extension :class:`mp.xt_3p` and can be used for power flow (PF), continuation power flow (CPF), and optimal power flow (OPF), by passing the extension as input to the :func:`run_pf`, :func:`run_cpf`, and :func:`run_opf` functions, respectively.

Some relevant reference documentation can be found in :ref:`ref_xt_3p_classes`, and the test code in |t_run_mp_3p_m|_ includes numerous examples of three-phase cases and how to run them.

Below is an example run.

::

>> mpopt = mpoption('verbose', 2);
>> run_pf('t_case3p_a', mpopt, 'mpx', mp.xt_3p)
MATPOWER Version 8.0b1+, 15-Feb-2024
Power Flow -- AC-polar-power formulation
it max residual max ∆x
---- -------------- --------------
0 2.375e+00 -
1 4.042e-01 2.287e-01
2 7.179e-02 7.961e-02
3 4.570e-03 1.967e-02
4 2.405e-05 1.400e-03
5 6.090e-10 6.908e-06
Newton's method converged in 5 iterations.
PF successful
PF succeeded in 0.23 seconds (0.22 setup + 0.01 solve)
================================================================================
| System Summary |
================================================================================
elements on off total
--------------------- ------- ------- -------
3-ph Buses 4 - 4
3-ph Generators 1 - 1
3-ph Loads 1 - 1
3-ph Lines 2 - 2
3-ph Transformers 1 - 1
Total 3-ph generation 6109.9 kW 4206.5 kVAr
Total 3-ph load 5450.0 kW 2442.6 kVAr
Total 3-ph line loss 561.5 kW 1173.8 kVAr
Total 3-ph transformer loss 98.4 kW 590.2 kVAr
================================================================================
| 3-ph Bus Data |
================================================================================
3-ph Phase A Voltage Phase B Voltage Phase C Voltage
Bus ID Status (kV) (deg) (kV) (deg) (kV) (deg)
-------- ------ ------- ------- ------- ------- ------- -------
1 1 7.1996 0.00 7.1996 -120.00 7.1996 120.00
2 1 7.1637 -0.14 7.1105 -120.18 7.0821 119.26
3 1 2.3055 -2.26 2.2547 -123.62 2.2028 114.79
4 1 2.1750 -4.12 1.9298 -126.80 1.8327 102.85
================================================================================
| 3-ph Generator Data |
================================================================================
3-ph 3-ph Phase A Power Phase B Power Phase C Power
Gen ID Bus ID Status (kW) (KVAr) (kW) (kVAr) (kW) (kVAr)
-------- -------- ------ ------- ------ ------- ------ ------- ------
1 1 1 1341.42 970.52 2096.10 1341.41 2672.34 1894.59
================================================================================
| 3-ph Load Data |
================================================================================
3-ph 3-ph Phase A Power Phase B Power Phase C Power
Load ID Bus ID Status (kW) (PF) (kW) (PF) (kW) (PF)
-------- -------- ------ ------- ------ ------- ------ ------- ------
1 4 1 1275.00 0.8500 1800.00 0.9000 2375.00 0.9500
================================================================================
| 3-ph Line Data |
================================================================================
--> Current Injections at "From" Bus
3-ph 3-ph Bus 3-ph Bus Phase A Current Phase B Current Phase C Current
Line ID From ID To ID Status (A) (deg) (A) (deg) (A) (deg)
-------- -------- -------- ------ ------ ------ ------ ------ ------ ------
1 1 2 1 229.97 -35.9 345.66 -152.6 455.00 84.7
2 3 4 1 689.64 -35.9 1036.34 -152.6 1364.10 84.7
<-- Current Injections at "To" Bus
3-ph 3-ph Bus 3-ph Bus Phase A Current Phase B Current Phase C Current
Line ID From ID To ID Status (A) (deg) (A) (deg) (A) (deg)
-------- -------- -------- ------ ------ ------ ------ ------ ------ ------
1 1 2 1 230.06 144.1 345.72 27.4 455.06 -95.3
2 3 4 1 689.66 144.1 1036.35 27.4 1364.11 -95.3
--> Power Injections at "From" Bus
3-ph 3-ph Bus 3-ph Bus Phase A Power Phase B Power Phase C Power
Line ID From ID To ID Status (kW) (kVAr) (kW) (kVAr) (kW) (kVAr)
-------- -------- -------- ------ ------ ------ ------ ------ ------ ------
1 1 2 1 1341.4 970.5 2096.1 1341.4 2672.3 1894.6
2 3 4 1 1323.5 881.1 2043.4 1133.3 2598.7 1508.6
<-- Power Injections at "To" Bus
3-ph 3-ph Bus 3-ph Bus Phase A Power Phase B Power Phase C Power
Line ID From ID To ID Status (kW) (kVAr) (kW) (kVAr) (kW) (kVAr)
-------- -------- -------- ------ ------ ------ ------ ------ ------ ------
1 1 2 1 -1337.2 -963.4 -2074.4 -1319.1 -2652.4 -1830.6
2 3 4 1 -1275.0 -790.2 -1800.0 -871.8 -2375.0 -780.6
================================================================================
| 3-ph Transformer Data |
================================================================================
--> Current Injections at "From" Bus
3-ph 3-ph Bus 3-ph Bus Phase A Current Phase B Current Phase C Current
Xfrm ID From ID To ID Status (A) (deg) (A) (deg) (A) (deg)
-------- -------- -------- ------ ------ ------ ------ ------ ------ ------
1 2 3 1 230.06 -35.9 345.72 -152.6 455.06 84.7
<-- Current Injections at "To" Bus
3-ph 3-ph Bus 3-ph Bus Phase A Current Phase B Current Phase C Current
Xfrm ID From ID To ID Status (A) (deg) (A) (deg) (A) (deg)
-------- -------- -------- ------ ------ ------ ------ ------ ------ ------
1 2 3 1 689.64 144.1 1036.34 27.4 1364.10 -95.3
--> Power Injections at "From" Bus
3-ph 3-ph Bus 3-ph Bus Phase A Power Phase B Power Phase C Power
Xfmr ID From ID To ID Status (kW) (kVAr) (kW) (kVAr) (kW) (kVAr)
-------- -------- -------- ------ ------ ------ ------ ------ ------ ------
1 2 3 1 1337.2 963.4 2074.4 1319.1 2652.4 1830.6
<-- Power Injections at "To" Bus
3-ph 3-ph Bus 3-ph Bus Phase A Power Phase B Power Phase C Power
Xfmr ID From ID To ID Status (kW) (kVAr) (kW) (kVAr) (kW) (kVAr)
-------- -------- -------- ------ ------ ------ ------ ------ ------ ------
1 2 3 1 -1323.5 -881.1 -2043.4 -1133.3 -2598.7 -1508.6


Data Format
-----------

The prototype examples included in |MATPOWER| 8 simply define a few extra fields in the standard |MATPOWER| case struct for the three-phase elements. The example above uses |t_case3p_a|_. This is a case with 4 three-phase buses, connected via 2 lines and 1 transformer, with a three-phase generator representing the substation at bus 1 and a three-phase load at bus 4.

The data for the individual elements are found in the fields ``bus3p``, ``line3p``, ``xfrm3p``, ``load3p``, and ``gen3p`` fields of ``mpc``. The ``lc`` field contains the per-mile impedance parameters for different line construction configurations referenced by the individual lines.

Besides the fields for the individual elements, cases with three-phase elements are also expected to include ``freq``, the system frequency in Hertz, and ``base_kVA``, the system per-unit kVA base for three-phase portions of the network.

::

function mpc = t_case3p_a
%T_CASE3P_A Four bus, unbalanced 3-phase test case.
%
% This data comes from 4Bus-YY-UnB.DSS, a modified version (with unbalanced
% load) of 4Bus-YY-Bal.DSS [1], the OpenDSS 4 bus IEEE test case with
% grounded-wye to grounded-wye transformer.
%
% [1] https://sourceforge.net/p/electricdss/code/HEAD/tree/trunk/Distrib/IEEETestCases/4Bus-YY-Bal/4Bus-YY-Bal.DSS
%% MATPOWER Case Format : Version 2
mpc.version = '2';
%%----- Power Flow Data -----%%
%% system MVA base
mpc.baseMVA = 100;
mpc.bus = [];
mpc.gen = [];
mpc.branch = [];
mpc.gencost = [];
%%----- 3 Phase Model Data -----%%
%% system data
mpc.freq = 60; %% frequency, Hz
mpc.basekVA = 1000; %% system kVA base
%% bus data
% busid type basekV Vm1 Vm2 Vm3 Va1 Va2 Va3
mpc.bus3p = [
1 3 12.47 1 1 1 0 -120 120;
2 1 12.47 1 1 1 0 -120 120;
3 1 4.16 1 1 1 0 -120 120;
4 1 4.16 1 1 1 0 -120 120;
];
%% branch data
% brid fbus tbus status lcid len
mpc.line3p = [
1 1 2 1 1 2000/5280;
2 3 4 1 1 2500/5280;
];
%% transformer
% xfid fbus tbus status R X basekVA basekV
mpc.xfmr3p = [
1 2 3 1 0.01 0.06 6000 12.47;
];
%% load
% ldid ldbus status Pd1 Pd2 Pd3 ldpf1 ldpf2 ldpf3
mpc.load3p = [
1 4 1 1275 1800 2375 0.85 0.9 0.95;
];
%% gen
% genid gbus status Vg1 Vg2 Vg3 Pg1 Pg2 Pg3 Qg1 Qg2 Qg3
mpc.gen3p = [
1 1 1 1 1 1 2000 2000 2000 0 0 0;
];
%% line construction
% lcid R11 R21 R31 R22 R32 R33 X11 X21 X31 X22 X32 X33 C11 C21 C31 C22 C32 C33
mpc.lc = [
1 0.457541 0.15594 0.153474 0.466617 0.157996 0.461462 1.078 0.501648 0.384909 1.04813 0.423624 1.06502 15.0671 -4.86241 -1.85323 15.875 -3.09098 14.3254
];


Example Cases
-------------

The following cases are included in |lib_t|_.

============= ================== ======= ======= ================
Name Description 3-phase 1-phase bus links
============= ================== ======= ======= ================
|t_case3p_a|_ 4 bus 3-phase case 4 -- --
|t_case3p_b|_ 6 bus hybrid case 4 2 1 PQ
|t_case3p_c|_ 6 bus hybrid case 4 2 1 PV (1-phase side)
|t_case3p_d|_ 6 bus hybrid case 4 2 1 PV (3-phase side)
|t_case3p_e|_ 5 bus hybrid case 4 1 1 REF (1-phase side)
|t_case3p_f|_ 21 bus hybrid case 12 9 3 PQ
|t_case3p_g|_ 21 bus hybrid case 12 9 3 REF-PQ, PV-PQ, PQ-PQ
|t_case3p_h|_ 21 bus hybrid case 12 9 3 REF-PQ, PQ-PV, PQ-PQ
============= ================== ======= ======= ================

The data for the 4 bus, three-phase system in |t_case3p_a|_ comes from ``4Bus-YY-UnB.DSS``, a modified version (with unbalanced load) of |4Bus_YY_Bal_DSS|_, the OpenDSS 4-bus IEEE test case with grounded-wye to grounded-wye transformer. [#]_

The five and six bus cases connect this 4-bus three-phase case to 1 or 2 single-phase buses. And the 21-bus cases are based on connecting three copies of the 4 bus three-phase case to the single-phase |case9|_.

.. |t_run_mp_3p_m| replace:: :file:`t_run_mp_3p.m`
.. |lib_t| replace:: :file:`lib/t`
.. |case9| replace:: :file:`case9.m`
.. |4Bus_YY_Bal_DSS| replace:: :file:`4Bus-YY-Bal.DSS`
.. |t_case3p_a| replace:: :file:`t_case3p_a.m`
.. |t_case3p_b| replace:: :file:`t_case3p_b.m`
.. |t_case3p_c| replace:: :file:`t_case3p_c.m`
.. |t_case3p_d| replace:: :file:`t_case3p_d.m`
.. |t_case3p_e| replace:: :file:`t_case3p_e.m`
.. |t_case3p_f| replace:: :file:`t_case3p_f.m`
.. |t_case3p_g| replace:: :file:`t_case3p_g.m`
.. |t_case3p_h| replace:: :file:`t_case3p_h.m`

.. [#] https://sourceforge.net/p/electricdss/code/HEAD/tree/trunk/Distrib/IEEETestCases/4Bus-YY-Bal/4Bus-YY-Bal.DSS
.. _t_run_mp_3p_m: https://github.com/MATPOWER/matpower/blob/master/lib/t/t_run_mp_3p.m
.. _lib_t: https://github.com/MATPOWER/matpower/blob/master/lib/t/
.. _case9: https://github.com/MATPOWER/matpower/blob/master/data/case9.m
.. _4Bus_YY_Bal_DSS: https://sourceforge.net/p/electricdss/code/HEAD/tree/trunk/Distrib/IEEETestCases/4Bus-YY-Bal/4Bus-YY-Bal.DSS
.. _t_case3p_a: https://github.com/MATPOWER/matpower/blob/master/lib/t/t_case3p_a.m
.. _t_case3p_b: https://github.com/MATPOWER/matpower/blob/master/lib/t/t_case3p_b.m
.. _t_case3p_c: https://github.com/MATPOWER/matpower/blob/master/lib/t/t_case3p_c.m
.. _t_case3p_d: https://github.com/MATPOWER/matpower/blob/master/lib/t/t_case3p_d.m
.. _t_case3p_e: https://github.com/MATPOWER/matpower/blob/master/lib/t/t_case3p_e.m
.. _t_case3p_f: https://github.com/MATPOWER/matpower/blob/master/lib/t/t_case3p_f.m
.. _t_case3p_g: https://github.com/MATPOWER/matpower/blob/master/lib/t/t_case3p_g.m
.. _t_case3p_h: https://github.com/MATPOWER/matpower/blob/master/lib/t/t_case3p_h.m
1 change: 1 addition & 0 deletions docs/sphinx/source/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ Currently, most of the User's Manuals are still available only as PDF, built fro

howto/element
howto/extension
howto/three-phase
howto/builddocs

------------------------------------
Expand Down
6 changes: 6 additions & 0 deletions lib/t/t_case3p_a.m
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
function mpc = t_case3p_a
%T_CASE3P_A Four bus, unbalanced 3-phase test case.
%
% This data comes from 4Bus-YY-UnB.DSS, a modified version (with unbalanced
% load) of 4Bus-YY-Bal.DSS [1], the OpenDSS 4 bus IEEE test case with
% grounded-wye to grounded-wye transformer.
%
% [1] https://sourceforge.net/p/electricdss/code/HEAD/tree/trunk/Distrib/IEEETestCases/4Bus-YY-Bal/4Bus-YY-Bal.DSS

%% MATPOWER Case Format : Version 2
mpc.version = '2';
Expand Down

0 comments on commit 87bb91b

Please sign in to comment.