There are two versions of the Matpowercase ﬁle format. Matpowerversions 3.0.0 and
earlier used the version 1 format internally. Subsequent versions of Matpowerhave 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 Matpowerare speciﬁed in a set of data
matrices packaged as the ﬁelds of a Matlabstruct, referred to as a “Matpowercase”
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 Matpowercase 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 Matpowercase format are given in the tables below and can also
be accessed by typing help caseformat at the Matlabprompt. 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 Matpowercase 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.^{61}
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.

Table B-1:Bus Data (mpc.bus)

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= 1.0 p.u.)

BS

6

shunt susceptance (MVAr injected at= 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 (/MW)

LAM_Q^{†}

15

Lagrange multiplier on reactive power mismatch (/MVAr)

MU_VMAX^{†}

16

Kuhn-Tucker multiplier on upper voltage limit (/p.u.)

MU_VMIN^{†}

17

Kuhn-Tucker multiplier on lower voltage limit (/p.u.)

^{†}Included in OPF output, typically not included (or ignored) in input matrix. Here we assume the objectivefunction has units.

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

name

column

description

GEN_BUS

1

bus number

PG

2

real power output (MW)

QG

3

reactive power output (MVAr)

QMAX

4

maximum reactive power output (MVAr)

QMIN

5

minimum reactive power output (MVAr)

VG^{‡}

6

voltage magnitude setpoint (p.u.)

MBASE

7

total MVA base of machine, defaults to baseMVA

GEN_STATUS

8

machine status,

= machine in-service

= machine out-of-service

PMAX

9

maximum real power output (MW)

PMIN

10

minimum real power output (MW)

PC1^{*}

11

lower real power output of PQ capability curve (MW)

PC2^{*}

12

upper real power output of PQ capability curve (MW)

QC1MIN^{*}

13

minimum reactive power output at PC1 (MVAr)

QC1MAX^{*}

14

maximum reactive power output at PC1 (MVAr)

QC2MIN^{*}

15

minimum reactive power output at PC2 (MVAr)

QC2MAX^{*}

16

maximum reactive power output at PC2 (MVAr)

RAMP_AGC^{*}

17

ramp rate for load following/AGC (MW/min)

RAMP_10^{*}

18

ramp rate for 10 minute reserves (MW)

RAMP_30^{*}

19

ramp rate for 30 minute reserves (MW)

RAMP_Q^{*}

20

ramp rate for reactive power (2 sec timescale) (MVAr/min)

APF^{*}

21

area participation factor

MU_PMAX^{†}

22

Kuhn-Tucker multiplier on upperlimit (/MW)

MU_PMIN^{†}

23

Kuhn-Tucker multiplier on lowerlimit (/MW)

MU_QMAX^{†}

24

Kuhn-Tucker multiplier on upperlimit (/MVAr)

MU_QMIN^{†}

25

Kuhn-Tucker multiplier on lowerlimit (/MVAr)

^{*}Not included in version 1 case format.^{†}Included in OPF output, typically not included (or ignored) in input matrix. Here we assume the objective function has units.^{‡}Used to determine voltage setpoint for optimal power ﬂow only if opf.use_vg option is non-zero (0 by default). Otherwise generator voltage range is determined by limitsset for corresponding bus in bus matrix.

Table B-3:Branch Data (mpc.branch)

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,;used to indicate transmission line ratherthan transformer, i.e. mathematically equivalent to transformerwith)

^{*}Used to specify branch ﬂow limits. By default these are limits on apparent power with units in MVA. However,the 'opf.flow_lim' option can be used to specify that the limits are active power or current, in which case theratings are speciﬁed in MW or (kA, respectively. For current this is equivalent to an MVA value ata 1 p.u. voltage.^{†}Not included in version 1 case format. The voltage angle diﬀerence is taken to be unbounded below if ANGMINand unbounded above if ANGMAX. If both parameters are zero, the voltage angle diﬀerence isunconstrained.^{‡}Included in power ﬂow and OPF output, ignored on input.^{§}Included in OPF output, typically not included (or ignored) in input matrix. Here we assume the objectivefunction has units.

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

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

numberof data points deﬁning an-segment piecewise linear cost

function, or of coeﬃcients deﬁning an-th order polynomial cost function

COST

5

parameters deﬁning total cost functionbegin in this column,

units ofandare $/hr and MW (or MVAr), respectively

(MODEL = 1)

whereand the costis deﬁned by

the coordinates,, …,

of the end/break-points of the piecewise linear cost

(MODEL = 2)

coeﬃcients of-th order polynomial cost function, starting

with highest order, where cost is

^{†}If gen hasrows, then the ﬁrstrows of gencost contain the costs for active power produced by the correspondinggenerators. If gencost hasrows, then rowsthroughcontain the reactive power costs in the same format.^{*}Not currently used by any Matpowerfunctions.

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ﬃcientof constant term of linear loss function (MW)

LOSS1

17

coeﬃcientof linear term of linear loss function (MW/MW)

(, whereis the ﬂow at the “from” end)

MU_PMIN^{‡}

18

Kuhn-Tucker multiplier on lower ﬂow limit at “from” bus (/MW)

MU_PMAX^{‡}

19

Kuhn-Tucker multiplier on upper ﬂow limit at “from” bus (/MW)

MU_QMINF^{‡}

20

Kuhn-Tucker multiplier on lower VAr limit at “from” bus (/MVAr)

MU_QMAXF^{‡}

21

Kuhn-Tucker multiplier on upper VAr limit at “from” bus (/MVAr)

MU_QMINT^{‡}

22

Kuhn-Tucker multiplier on lower VAr limit at “to” bus (/MVAr)

MU_QMAXT^{‡}

23

Kuhn-Tucker multiplier on upper VAr limit at “to” bus (/MVAr)

^{*}Requires explicit use of toggle_dcline.^{†}Output column, value updated by power ﬂow or OPF (except PF in case of simple power ﬂow).^{‡}Included in OPF output, typically not included (or ignored) in input matrix. Here we assume the objective function hasunits.