1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 """Defines the PYPOWER case file format.
18
19 A PYPOWER case file is a Python file or MAT-file that defines or returns
20 a dict named ppc, referred to as a "PYPOWER case dict". The keys
21 of this dict are C{baseMVA}, C{bus}, C{gen}, C{branch}, and (optional)
22 C{gencost}. With the exception of C{baseMVA}, a scalar, each data variable
23 is an array, where a row corresponds to a single bus, branch, gen, etc. The
24 format of the data is similar to the PTI format described in
25
26 U{http://www.ee.washington.edu/research/pstca/formats/pti.txt}
27
28 PYPOWER Case Version Information:
29 =================================
30
31 There are two versions of the PYPOWER case file format. The current
32 version of PYPOWER uses version 2 of the PYPOWER case format
33 internally, and includes a 'version' field with a value of '2' to make
34 the version explicit. Earlier versions of PYPOWER used the version 1
35 case format, which defined the data matrices as individual variables,
36 as opposed to keys of a dict. Case files in version 1 format with
37 OPF data also included an (unused) 'areas' variable. While the version 1
38 format has now been deprecated, it is still be handled automatically by
39 L{loadcase} and L{savecase} which are able to load and save case files in both
40 version 1 and version 2 formats.
41
42 See also L{idx_bus}, L{idx_brch}, L{idx_gen}, L{idx_area} and L{idx_cost}
43 regarding constants which can be used as named column indices for the data
44 matrices. Also described in the first three are additional results columns
45 that are added to the bus, branch and gen matrices by the power flow and OPF
46 solvers.
47
48 The case dict also also allows for additional fields to be included.
49 The OPF is designed to recognize fields named C{A}, C{l}, C{u}, C{H}, C{Cw},
50 C{N}, C{fparm}, C{z0}, C{zl} and C{zu} as parameters used to directly extend
51 the OPF formulation (see L{opf} for details). Other user-defined fields may
52 also be included and will be automatically loaded by the L{loadcase} function
53 and, given an appropriate 'savecase' callback function (see
54 L{add_userfcn}), saved by the L{savecase} function.
55
56 Bus Data Format
57 ---------------
58
59 1. bus number (positive integer)
60 2. bus type
61 - PQ bus = 1
62 - PV bus = 2
63 - reference bus = 3
64 - isolated bus = 4
65 3. C{Pd}, real power demand (MW)
66 4. C{Qd}, reactive power demand (MVAr)
67 5. C{Gs}, shunt conductance (MW demanded at V = 1.0 p.u.)
68 6. C{Bs}, shunt susceptance (MVAr injected at V = 1.0 p.u.)
69 7. area number, (positive integer)
70 8. C{Vm}, voltage magnitude (p.u.)
71 9. C{Va}, voltage angle (degrees)
72 10. C{baseKV}, base voltage (kV)
73 11. C{zone}, loss zone (positive integer)
74 12. C{maxVm}, maximum voltage magnitude (p.u.)
75 13. C{minVm}, minimum voltage magnitude (p.u.)
76
77 Generator Data Format
78 ---------------------
79
80 1. bus number
81 2. C{Pg}, real power output (MW)
82 3. C{Qg}, reactive power output (MVAr)
83 4. C{Qmax}, maximum reactive power output (MVAr)
84 5. C{Qmin}, minimum reactive power output (MVAr)
85 6. C{Vg}, voltage magnitude setpoint (p.u.)
86 7. C{mBase}, total MVA base of this machine, defaults to baseMVA
87 8. status,
88 - C{> 0} - machine in service
89 - C{<= 0} - machine out of service
90 9. C{Pmax}, maximum real power output (MW)
91 10. C{Pmin}, minimum real power output (MW)
92 11. C{Pc1}, lower real power output of PQ capability curve (MW)
93 12. C{Pc2}, upper real power output of PQ capability curve (MW)
94 13. C{Qc1min}, minimum reactive power output at Pc1 (MVAr)
95 14. C{Qc1max}, maximum reactive power output at Pc1 (MVAr)
96 15. C{Qc2min}, minimum reactive power output at Pc2 (MVAr)
97 16. C{Qc2max}, maximum reactive power output at Pc2 (MVAr)
98 17. ramp rate for load following/AGC (MW/min)
99 18. ramp rate for 10 minute reserves (MW)
100 19. ramp rate for 30 minute reserves (MW)
101 20. ramp rate for reactive power (2 sec timescale) (MVAr/min)
102 21. APF, area participation factor
103
104 Branch Data Format
105 ------------------
106
107 1. C{f}, from bus number
108 2. C{t}, to bus number
109 3. C{r}, resistance (p.u.)
110 4. C{x}, reactance (p.u.)
111 5. C{b}, total line charging susceptance (p.u.)
112 6. C{rateA}, MVA rating A (long term rating)
113 7. C{rateB}, MVA rating B (short term rating)
114 8. C{rateC}, MVA rating C (emergency rating)
115 9. C{ratio}, transformer off nominal turns ratio ( = 0 for lines )
116 10. C{angle}, transformer phase shift angle (degrees), positive => delay
117 (Gf, shunt conductance at from bus p.u.)
118 (Bf, shunt susceptance at from bus p.u.)
119 (Gt, shunt conductance at to bus p.u.)
120 (Bt, shunt susceptance at to bus p.u.)
121 11. initial branch status, 1 - in service, 0 - out of service
122 12. minimum angle difference, angle(Vf) - angle(Vt) (degrees)
123 13. maximum angle difference, angle(Vf) - angle(Vt) (degrees)
124
125 Generator Cost Data Format
126 --------------------------
127
128 NOTE: If C{gen} has C{ng} rows, then the first C{ng} rows of gencost contain
129 the cost for active power produced by the corresponding generators.
130 If C{gencost} has 2*ng rows then rows C{ng+1} to C{2*ng} contain the reactive
131 power costs in the same format.
132
133 1. C{model}, 1 - piecewise linear, 2 - polynomial
134 2. C{startup}, startup cost in US dollars
135 3. C{shutdown}, shutdown cost in US dollars
136 4. C{N}, number of cost coefficients to follow for polynomial
137 cost function, or number of data points for piecewise linear
138 5. and following, parameters defining total cost function C{f(p)},
139 units of C{f} and C{p} are $/hr and MW (or MVAr), respectively.
140 (MODEL = 1) : C{p0, f0, p1, f1, ..., pn, fn}
141 where C{p0 < p1 < ... < pn} and the cost C{f(p)} is defined by
142 the coordinates C{(p0,f0), (p1,f1), ..., (pn,fn)} of the
143 end/break-points of the piecewise linear cost function
144 (MODEL = 2) : C{cn, ..., c1, c0}
145 C{n+1} coefficients of an C{n}-th order polynomial cost function,
146 starting with highest order, where cost is
147 C{f(p) = cn*p^n + ... + c1*p + c0}
148
149 Area Data Format (deprecated)
150 -----------------------------
151
152 (this data is not used by PYPOWER and is no longer necessary for
153 version 2 case files with OPF data).
154 1. C{i}, area number
155 2. C{price_ref_bus}, reference bus for that area
156
157 @see: L{loadcase}, L{savecase}, L{idx_bus}, L{idx_brch}, L{idx_gen},
158 L{idx_area} L{idx_cost}
159
160 @author: Ray Zimmerman (PSERC Cornell)
161 @author: Richard Lincoln
162 """
163