CASEFORMAT Defines the MATPOWER case file format.
A MATPOWER case file is an M-file or MAT-file that defines or returns
a struct named mpc, referred to as a "MATPOWER case struct". The fields
of this struct are baseMVA, bus, gen, branch, and (optional) gencost. With
the exception of baseMVA, a scalar, each data variable is a matrix, where
a row corresponds to a single bus, branch, gen, etc. The format of the
data is similar to the PTI format described in
https://labs.ece.uw.edu/pstca/formats/pti.txt
except where noted. An item marked with (+) indicates that it is included
in this data but is not part of the PTI format. An item marked with (-) is
one that is in the PTI format but is not included here. Those marked with
(2) were added for version 2 of the case file format. The columns for
each data matrix are given below.
MATPOWER Case Version Information:
There are two versions of the MATPOWER case file format. The current
version of MATPOWER uses version 2 of the MATPOWER case format
internally, and includes a 'version' field with a value of '2' to make
the version explicit. Earlier versions of MATPOWER used the version 1
case format, which defined the data matrices as individual variables,
as opposed to fields of a struct. Case files in version 1 format with
OPF data also included an (unused) 'areas' variable. While the version 1
format has now been deprecated, it is still be handled automatically by
LOADCASE and SAVECASE which are able to load and save case files in both
version 1 and version 2 formats.
See also IDX_BUS, IDX_BRCH, IDX_GEN, IDX_AREA and IDX_COST regarding
constants which can be used as named column indices for the data matrices.
Also described in the first three are additional results columns that
are added to the bus, branch and gen matrices by the power flow and OPF
solvers.
The case struct also allows for additional fields to be included.
The OPF is designed to recognize fields named A, l, u, H, Cw, N,
fparm, z0, zl and zu as parameters used to directly extend the OPF
formulation (see OPF for details). Additional standard optional fields
include bus_name, gentype and genfuel. Other user-defined fields may also
be included and will be automatically loaded by the LOADCASE function
and, given an appropriate 'savecase' callback function (see
ADD_USERFCN), saved by the SAVECASE function.
Bus Data Format
1 bus number (positive integer)
2 bus type
PQ bus = 1
PV bus = 2
reference bus = 3
isolated bus = 4
3 Pd, real power demand (MW)
4 Qd, reactive power demand (MVAr)
5 Gs, shunt conductance (MW demanded at V = 1.0 p.u.)
6 Bs, shunt susceptance (MVAr injected at V = 1.0 p.u.)
7 area number, (positive integer)
8 Vm, voltage magnitude (p.u.)
9 Va, voltage angle (degrees)
(-) (bus name)
10 baseKV, base voltage (kV)
11 zone, loss zone (positive integer)
(+) 12 maxVm, maximum voltage magnitude (p.u.)
(+) 13 minVm, minimum voltage magnitude (p.u.)
Generator Data Format
1 bus number
(-) (machine identifier, 0-9, A-Z)
2 Pg, real power output (MW)
3 Qg, reactive power output (MVAr)
4 Qmax, maximum reactive power output (MVAr)
5 Qmin, minimum reactive power output (MVAr)
6 Vg, voltage magnitude setpoint (p.u.)
(-) (remote controlled bus index)
7 mBase, total MVA base of this machine, defaults to baseMVA
(-) (machine impedance, p.u. on mBase)
(-) (step up transformer impedance, p.u. on mBase)
(-) (step up transformer off nominal turns ratio)
8 status, > 0 - machine in service
<= 0 - machine out of service
(-) (% of total VAr's to come from this gen in order to hold V at
remote bus controlled by several generators)
9 Pmax, maximum real power output (MW)
10 Pmin, minimum real power output (MW)
(2) 11 Pc1, lower real power output of PQ capability curve (MW)
(2) 12 Pc2, upper real power output of PQ capability curve (MW)
(2) 13 Qc1min, minimum reactive power output at Pc1 (MVAr)
(2) 14 Qc1max, maximum reactive power output at Pc1 (MVAr)
(2) 15 Qc2min, minimum reactive power output at Pc2 (MVAr)
(2) 16 Qc2max, maximum reactive power output at Pc2 (MVAr)
(2) 17 ramp rate for load following/AGC (MW/min)
(2) 18 ramp rate for 10 minute reserves (MW)
(2) 19 ramp rate for 30 minute reserves (MW)
(2) 20 ramp rate for reactive power (2 sec timescale) (MVAr/min)
(2) 21 APF, area participation factor
Branch Data Format
1 f, from bus number
2 t, to bus number
(-) (circuit identifier)
3 r, resistance (p.u.)
4 x, reactance (p.u.)
5 b, total line charging susceptance (p.u.)
6 rateA, MVA rating A (long term rating), set to 0 for unlimited
7 rateB, MVA rating B (short term rating), set to 0 for unlimited
8 rateC, MVA rating C (emergency rating), set to 0 for unlimited
9 tap, transformer off nominal turns ratio, if non-zero
(taps at "from" bus, impedance at "to" bus, i.e. if r = x = b = 0,
then tap = Vf / Vt; tap = 0 used to indicate transmission
line rather than transformer, i.e. mathematically equivalent to
transformer with tap = 1)
10 shift, transformer phase shift angle (degrees), positive => delay
(-) (Gf, shunt conductance at from bus p.u.)
(-) (Bf, shunt susceptance at from bus p.u.)
(-) (Gt, shunt conductance at to bus p.u.)
(-) (Bt, shunt susceptance at to bus p.u.)
11 initial branch status, 1 - in service, 0 - out of service
(2) 12 minimum angle difference, angle(Vf) - angle(Vt) (degrees)
(2) 13 maximum angle difference, angle(Vf) - angle(Vt) (degrees)
(The voltage angle difference is taken to be unbounded below
if ANGMIN < -360 and unbounded above if ANGMAX > 360.
If both parameters are zero, it is unconstrained.)
(+) Generator Cost Data Format
NOTE: If gen has ng rows, then the first ng rows of gencost contain
the cost for active power produced by the corresponding generators.
If gencost has 2*ng rows then rows ng+1 to 2*ng contain the reactive
power costs in the same format.
1 model, 1 - piecewise linear, 2 - polynomial
2 startup, startup cost in US dollars
3 shutdown, shutdown cost in US dollars
4 N (= n+1), number of data points to follow defining an n-segment
piecewise linear cost function, or of cost coefficients defining
an n-th order polynomial cost function
5 and following, parameters defining total cost function f(p),
units of f and p are $/hr and MW (or MVAr), respectively.
(MODEL = 1) : p1, f1, p2, f2, ..., pN, fN
where p1 < p2 < ... < pN and the cost f(p) is defined by
the coordinates (p1,f1), (p2,f2), ..., (pN,fN) of the
end/break-points of the piecewise linear cost function
(MODEL = 2) : cn, ..., c1, c0
N coefficients of an n-th order polynomial cost function,
starting with highest order, where cost is
f(p) = cn*p^n + ... + c1*p + c0
(+) Area Data Format (deprecated)
(this data is not used by MATPOWER and is no longer necessary for
version 2 case files with OPF data).
1 i, area number
2 price_ref_bus, reference bus for that area
See also LOADCASE, SAVECASE, IDX_BUS, IDX_BRCH, IDX_GEN, IDX_AREA
and IDX_COST.0001 %CASEFORMAT Defines the MATPOWER case file format. 0002 % A MATPOWER case file is an M-file or MAT-file that defines or returns 0003 % a struct named mpc, referred to as a "MATPOWER case struct". The fields 0004 % of this struct are baseMVA, bus, gen, branch, and (optional) gencost. With 0005 % the exception of baseMVA, a scalar, each data variable is a matrix, where 0006 % a row corresponds to a single bus, branch, gen, etc. The format of the 0007 % data is similar to the PTI format described in 0008 % https://labs.ece.uw.edu/pstca/formats/pti.txt 0009 % except where noted. An item marked with (+) indicates that it is included 0010 % in this data but is not part of the PTI format. An item marked with (-) is 0011 % one that is in the PTI format but is not included here. Those marked with 0012 % (2) were added for version 2 of the case file format. The columns for 0013 % each data matrix are given below. 0014 % 0015 % MATPOWER Case Version Information: 0016 % There are two versions of the MATPOWER case file format. The current 0017 % version of MATPOWER uses version 2 of the MATPOWER case format 0018 % internally, and includes a 'version' field with a value of '2' to make 0019 % the version explicit. Earlier versions of MATPOWER used the version 1 0020 % case format, which defined the data matrices as individual variables, 0021 % as opposed to fields of a struct. Case files in version 1 format with 0022 % OPF data also included an (unused) 'areas' variable. While the version 1 0023 % format has now been deprecated, it is still be handled automatically by 0024 % LOADCASE and SAVECASE which are able to load and save case files in both 0025 % version 1 and version 2 formats. 0026 % 0027 % See also IDX_BUS, IDX_BRCH, IDX_GEN, IDX_AREA and IDX_COST regarding 0028 % constants which can be used as named column indices for the data matrices. 0029 % Also described in the first three are additional results columns that 0030 % are added to the bus, branch and gen matrices by the power flow and OPF 0031 % solvers. 0032 % 0033 % The case struct also allows for additional fields to be included. 0034 % The OPF is designed to recognize fields named A, l, u, H, Cw, N, 0035 % fparm, z0, zl and zu as parameters used to directly extend the OPF 0036 % formulation (see OPF for details). Additional standard optional fields 0037 % include bus_name, gentype and genfuel. Other user-defined fields may also 0038 % be included and will be automatically loaded by the LOADCASE function 0039 % and, given an appropriate 'savecase' callback function (see 0040 % ADD_USERFCN), saved by the SAVECASE function. 0041 % 0042 % Bus Data Format 0043 % 1 bus number (positive integer) 0044 % 2 bus type 0045 % PQ bus = 1 0046 % PV bus = 2 0047 % reference bus = 3 0048 % isolated bus = 4 0049 % 3 Pd, real power demand (MW) 0050 % 4 Qd, reactive power demand (MVAr) 0051 % 5 Gs, shunt conductance (MW demanded at V = 1.0 p.u.) 0052 % 6 Bs, shunt susceptance (MVAr injected at V = 1.0 p.u.) 0053 % 7 area number, (positive integer) 0054 % 8 Vm, voltage magnitude (p.u.) 0055 % 9 Va, voltage angle (degrees) 0056 % (-) (bus name) 0057 % 10 baseKV, base voltage (kV) 0058 % 11 zone, loss zone (positive integer) 0059 % (+) 12 maxVm, maximum voltage magnitude (p.u.) 0060 % (+) 13 minVm, minimum voltage magnitude (p.u.) 0061 % 0062 % Generator Data Format 0063 % 1 bus number 0064 % (-) (machine identifier, 0-9, A-Z) 0065 % 2 Pg, real power output (MW) 0066 % 3 Qg, reactive power output (MVAr) 0067 % 4 Qmax, maximum reactive power output (MVAr) 0068 % 5 Qmin, minimum reactive power output (MVAr) 0069 % 6 Vg, voltage magnitude setpoint (p.u.) 0070 % (-) (remote controlled bus index) 0071 % 7 mBase, total MVA base of this machine, defaults to baseMVA 0072 % (-) (machine impedance, p.u. on mBase) 0073 % (-) (step up transformer impedance, p.u. on mBase) 0074 % (-) (step up transformer off nominal turns ratio) 0075 % 8 status, > 0 - machine in service 0076 % <= 0 - machine out of service 0077 % (-) (% of total VAr's to come from this gen in order to hold V at 0078 % remote bus controlled by several generators) 0079 % 9 Pmax, maximum real power output (MW) 0080 % 10 Pmin, minimum real power output (MW) 0081 % (2) 11 Pc1, lower real power output of PQ capability curve (MW) 0082 % (2) 12 Pc2, upper real power output of PQ capability curve (MW) 0083 % (2) 13 Qc1min, minimum reactive power output at Pc1 (MVAr) 0084 % (2) 14 Qc1max, maximum reactive power output at Pc1 (MVAr) 0085 % (2) 15 Qc2min, minimum reactive power output at Pc2 (MVAr) 0086 % (2) 16 Qc2max, maximum reactive power output at Pc2 (MVAr) 0087 % (2) 17 ramp rate for load following/AGC (MW/min) 0088 % (2) 18 ramp rate for 10 minute reserves (MW) 0089 % (2) 19 ramp rate for 30 minute reserves (MW) 0090 % (2) 20 ramp rate for reactive power (2 sec timescale) (MVAr/min) 0091 % (2) 21 APF, area participation factor 0092 % 0093 % Branch Data Format 0094 % 1 f, from bus number 0095 % 2 t, to bus number 0096 % (-) (circuit identifier) 0097 % 3 r, resistance (p.u.) 0098 % 4 x, reactance (p.u.) 0099 % 5 b, total line charging susceptance (p.u.) 0100 % 6 rateA, MVA rating A (long term rating), set to 0 for unlimited 0101 % 7 rateB, MVA rating B (short term rating), set to 0 for unlimited 0102 % 8 rateC, MVA rating C (emergency rating), set to 0 for unlimited 0103 % 9 tap, transformer off nominal turns ratio, if non-zero 0104 % (taps at "from" bus, impedance at "to" bus, i.e. if r = x = b = 0, 0105 % then tap = Vf / Vt; tap = 0 used to indicate transmission 0106 % line rather than transformer, i.e. mathematically equivalent to 0107 % transformer with tap = 1) 0108 % 10 shift, transformer phase shift angle (degrees), positive => delay 0109 % (-) (Gf, shunt conductance at from bus p.u.) 0110 % (-) (Bf, shunt susceptance at from bus p.u.) 0111 % (-) (Gt, shunt conductance at to bus p.u.) 0112 % (-) (Bt, shunt susceptance at to bus p.u.) 0113 % 11 initial branch status, 1 - in service, 0 - out of service 0114 % (2) 12 minimum angle difference, angle(Vf) - angle(Vt) (degrees) 0115 % (2) 13 maximum angle difference, angle(Vf) - angle(Vt) (degrees) 0116 % (The voltage angle difference is taken to be unbounded below 0117 % if ANGMIN < -360 and unbounded above if ANGMAX > 360. 0118 % If both parameters are zero, it is unconstrained.) 0119 % 0120 % (+) Generator Cost Data Format 0121 % NOTE: If gen has ng rows, then the first ng rows of gencost contain 0122 % the cost for active power produced by the corresponding generators. 0123 % If gencost has 2*ng rows then rows ng+1 to 2*ng contain the reactive 0124 % power costs in the same format. 0125 % 1 model, 1 - piecewise linear, 2 - polynomial 0126 % 2 startup, startup cost in US dollars 0127 % 3 shutdown, shutdown cost in US dollars 0128 % 4 N (= n+1), number of data points to follow defining an n-segment 0129 % piecewise linear cost function, or of cost coefficients defining 0130 % an n-th order polynomial cost function 0131 % 5 and following, parameters defining total cost function f(p), 0132 % units of f and p are $/hr and MW (or MVAr), respectively. 0133 % (MODEL = 1) : p1, f1, p2, f2, ..., pN, fN 0134 % where p1 < p2 < ... < pN and the cost f(p) is defined by 0135 % the coordinates (p1,f1), (p2,f2), ..., (pN,fN) of the 0136 % end/break-points of the piecewise linear cost function 0137 % (MODEL = 2) : cn, ..., c1, c0 0138 % N coefficients of an n-th order polynomial cost function, 0139 % starting with highest order, where cost is 0140 % f(p) = cn*p^n + ... + c1*p + c0 0141 % 0142 % (+) Area Data Format (deprecated) 0143 % (this data is not used by MATPOWER and is no longer necessary for 0144 % version 2 case files with OPF data). 0145 % 1 i, area number 0146 % 2 price_ref_bus, reference bus for that area 0147 % 0148 % See also LOADCASE, SAVECASE, IDX_BUS, IDX_BRCH, IDX_GEN, IDX_AREA 0149 % and IDX_COST. 0150 0151 % MATPOWER 0152 % Copyright (c) 1996-2019, Power Systems Engineering Research Center (PSERC) 0153 % by Ray Zimmerman, PSERC Cornell 0154 % 0155 % This file is part of MATPOWER. 0156 % Covered by the 3-clause BSD License (see LICENSE file for details). 0157 % See https://matpower.org for more info.