Data File Format

There are two versions of the Matpower case ﬁle format. Matpower versions 3.0.0 and earlier used the version 1 format internally. Subsequent versions of Matpower have used the version 2 format described below, though version 1 ﬁles are still handled, and converted automatically, by the loadcase and savecase functions.

In the version 2 format, the input data for Matpower are speciﬁed in a set of data matrices packaged as the ﬁelds of a Matlab struct, referred to as a “Matpower case” struct and conventionally denoted by the variable mpc. This struct is typically deﬁned in a case ﬁle, either a function M-ﬁle whose return value is the mpc struct or a MAT-ﬁle that deﬁnes a variable named mpc when loaded. The ﬁelds of this struct are baseMVA, bus, branch, gen and, optionally, gencost. The baseMVA ﬁeld is a scalar and the rest are matrices. Each row in the data matrices corresponds to a single bus, branch, or generator and the columns are similar to the columns in the standard IEEE and PTI formats. The mpc struct also has a version ﬁeld whose value is a string set to the current Matpower case version, currently '2' by default. The version 1 case format deﬁnes the data matrices as individual variables rather than ﬁelds of a struct, and some do not include all of the columns deﬁned in version 2.

Numerous examples can be found in the case ﬁles listed in Table D-18 in Appendix D. The case ﬁles created by savecase use a tab-delimited format for the data matrices to make it simple to transfer data seamlessly back and forth between a text editor and a spreadsheet via simple copy and paste.

The details of the Matpower case format are given in the tables below and can also be accessed by typing help caseformat at the Matlab prompt. First, the baseMVA ﬁeld is a simple scalar value specifying the system MVA base used for converting power into per unit quantities. For convenience and code portability, idx_bus deﬁnes a set of constants to be used as named indices into the columns of the bus matrix. Similarly, idx_brch, idx_gen and idx_cost deﬁne names for the columns of branch, gen and gencost, respectively. The script define_constants provides a simple way to deﬁne all the usual constants at one shot. These are the names that appear in the ﬁrst column of the tables below.

The Matpower case format also allows for additional ﬁelds to be included in the structure. The OPF is designed to recognize ﬁelds named A, l, u, H, Cw, N, fparm, z0, zl and zu as parameters used to directly extend the OPF formulation as described in Section 7.1. Additional standard optional ﬁelds include bus_name, gentype and genfuel.⁶¹ Other user-deﬁned ﬁelds may also be included, such as the reserves ﬁeld used in the example code throughout Section 7.3. The loadcase function will automatically load any extra ﬁelds from a case ﬁle and, if the appropriate 'savecase' callback function (see Section 7.3.5) is added via add_userfcn, savecase will also save them back to a case ﬁle.

> 0 — Table B-2:Generator Data (mpc.gen)

≤ 0 — Table B-2:Generator Data (mpc.gen)

r = x = b = 0 — Table B-3:Branch Data (mpc.branch)

tap = |V|Vft|| — Table B-3:Branch Data (mpc.branch)

N = n + 1 — Table B-4:Generator Cost Data^† (mpc.gencost)

Table B-4:Generator Cost Data^† (mpc.gencost)

name	column	description
BUS_I	1	bus number (positive integer)
BUS_TYPE	2	bus type (1 = PQ, 2 = PV, 3 = ref, 4 = isolated)
PD	3	real power demand (MW)
QD	4	reactive power demand (MVAr)
GS	5	shunt conductance (MW demanded at $V$ = 1.0 p.u.)
BS	6	shunt susceptance (MVAr injected at $V$ = 1.0 p.u.)
BUS_AREA	7	area number (positive integer)
VM	8	voltage magnitude (p.u.)
VA	9	voltage angle (degrees)
BASE_KV	10	base voltage (kV)
ZONE	11	loss zone (positive integer)
VMAX	12	maximum voltage magnitude (p.u.)
VMIN	13	minimum voltage magnitude (p.u.)
LAM_P^†	14	Lagrange multiplier on real power mismatch ( $u$ /MW)
LAM_Q^†	15	Lagrange multiplier on reactive power mismatch ( $u$ /MVAr)
MU_VMAX^†	16	Kuhn-Tucker multiplier on upper voltage limit ( $u$ /p.u.)
MU_VMIN^†	17	Kuhn-Tucker multiplier on lower voltage limit ( $u$ /p.u.)

name	column	description
F_BUS	1	“from” bus number
T_BUS	2	“to” bus number
BR_R	3	resistance (p.u.)
BR_X	4	reactance (p.u.)
BR_B	5	total line charging susceptance (p.u.)
RATE_A^*	6	MVA rating A (long term rating), set to 0 for unlimited
RATE_B^*	7	MVA rating B (short term rating), set to 0 for unlimited
RATE_C^*	8	MVA rating C (emergency rating), set to 0 for unlimited
TAP	9	transformer oﬀ nominal turns ratio, if non-zero (taps at “from” bus, impedance at “to” bus, i.e. if $r = x = b = 0$ , $tap = \|V\|Vft\|\|$ ; $tap = 0$ used to indicate transmission line rather than transformer, i.e. mathematically equivalent to transformer with $tap = 1$ )
SHIFT	10	transformer phase shift angle (degrees), positive $⇒$ delay
BR_STATUS	11	initial branch status, 1 = in-service, 0 = out-of-service
ANGMIN^†	12	minimum angle diﬀerence, $𝜃f − 𝜃t$ (degrees)
ANGMAX^†	13	maximum angle diﬀerence, $𝜃 − 𝜃 f t$ (degrees)
PF^‡	14	real power injected at “from” bus end (MW)
QF^‡	15	reactive power injected at “from” bus end (MVAr)
PT^‡	16	real power injected at “to” bus end (MW)
QT^‡	17	reactive power injected at “to” bus end (MVAr)
MU_SF^§	18	Kuhn-Tucker multiplier on MVA limit at “from” bus ( $u$ /MVA)
MU_ST^§	19	Kuhn-Tucker multiplier on MVA limit at “to” bus ( $u$ /MVA)
MU_ANGMIN^§	20	Kuhn-Tucker multiplier lower angle diﬀerence limit ( $u$ /degree)
MU_ANGMAX^§	21	Kuhn-Tucker multiplier upper angle diﬀerence limit ( $u$ /degree)

name	column	description
MODEL	1	cost model, 1 = piecewise linear, 2 = polynomial
STARTUP	2	startup cost in US dollars^*
SHUTDOWN	3	shutdown cost in US dollars^*
NCOST	4	number $N = n + 1$ of data points deﬁning an $n$ -segment piecewise linear cost
		function, or of coeﬃcients deﬁning an $n$ -th order polynomial cost function
COST	5	parameters deﬁning total cost function $f(p)$ begin in this column,
		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 deﬁned by
		the coordinates $(p1,f1)$ , $(p2,f2)$ , …, $(pN,fN )$
		of the end/break-points of the piecewise linear cost
		(MODEL = 2) $⇒ cn,...,c1,c0$
		$N$ coeﬃcients of $n$ -th order polynomial cost function, starting
		with highest order, where cost is $f(p) = cnpn + ⋅⋅⋅+ c1p + c0$

name	column	description
F_BUS	1	“from” bus number
T_BUS	2	“to” bus number
BR_STATUS	3	initial branch status, 1 = in-service, 0 = out-of-service
PF^†	4	real power ﬂow at “from” bus end (MW), “from” $→$ “to”
PT^†	5	real power ﬂow at “to” bus end (MW), “from” $→$ “to”
QF^†	6	reactive power injected into “from” bus (MVAr)
QT^†	7	reactive power injected into “to” bus (MVAr)
VF	8	voltage magnitude setpoint at “from” bus (p.u.)
VT	9	voltage magnitude setpoint at “to” bus (p.u.)
PMIN	10	if positive (negative), lower limit on PF (PT)
PMAX	11	if positive (negative), upper limit on PF (PT)
QMINF	12	lower limit on reactive power injection into “from” bus (MVAr)
QMAXF	13	upper limit on reactive power injection into “from” bus (MVAr)
QMINT	14	lower limit on reactive power injection into “to” bus (MVAr)
QMAXT	15	upper limit on reactive power injection into “to” bus (MVAr)
LOSS0	16	coeﬃcient $l 0$ of constant term of linear loss function (MW)
LOSS1	17	coeﬃcient $l1$ of linear term of linear loss function (MW/MW)
		( $ploss = l0 +l1pf$ , where $pf$ is the ﬂow at the “from” end)
MU_PMIN^‡	18	Kuhn-Tucker multiplier on lower ﬂow limit at “from” bus ( $u$ /MW)
MU_PMAX^‡	19	Kuhn-Tucker multiplier on upper ﬂow limit at “from” bus ( $u$ /MW)
MU_QMINF^‡	20	Kuhn-Tucker multiplier on lower VAr limit at “from” bus ( $u$ /MVAr)
MU_QMAXF^‡	21	Kuhn-Tucker multiplier on upper VAr limit at “from” bus ( $u$ /MVAr)
MU_QMINT^‡	22	Kuhn-Tucker multiplier on lower VAr limit at “to” bus ( $u$ /MVAr)
MU_QMAXT^‡	23	Kuhn-Tucker multiplier on upper VAr limit at “to” bus ( $u$ /MVAr)

B Data File Format