=============================================================
 MATPOWER - Matlab routines for solving power flow problems.
=============================================================

Version:    1.0

Home Page:  http://www.pserc.cornell.edu/matpower/matpower.html

Authors:    Ray Zimmerman           <rz10@cornell.edu>
            Deqiang (David) Gan     <deqiang@ee.cornell.edu>

            Wed, Sep 17, 1997

Copyright (c) 1997 by Power System Engineering Research Center (PSERC)
See http://www.pserc.cornell.edu/ for more info.


--------------
 INTRODUCTION
--------------

MATPOWER is a package of Matlab m-files for solving 3 types of power
flow algorithms: PF, OPF, UOPF. These refer to, respectively, a standard
Newton-Raphson power flow, an optimal power flow, and an optimal power
flow with a unit-commitment heuristic which allows expensive generators
to be shut down. This code was developed specifically for use in the
PowerWeb project (see http://www.pserc.cornell.edu/powerweb/).

Aside from this file, more documentation can be found in the m-files
themselves (type: help <name of m-file> at the Matlab prompt), and the
techinfo.pdf file. Documentation for the case file format can be found
in case.m. Where something is still unclear, the source code IS the
documentation :-)

Thanks to Chris DeMarco, one of our PSERC associates at the University
of Wisconsin, for his contributions, specifically for the technique used
to build the Jacobian matrix in MATPOWER.


-------------
 QUICK START
-------------

What you need:
    Matlab 4 or higher
    Optimization Toolbox (for some OPF algorithms)

Installation:
    Copy all of the m-files in the MATPOWER distribution into your
    Matlab path.

To run a simple power flow:
    At the matlab prompt, type: runpf

To run an optimal power flow:
    At the matlab prompt, type: runopf

To run a different case (e.g. case300.m or case57.m):
    At the matlab prompt, type: runpf('case300')
                            or: runopf('case57')

For info on other parameters:
    At the matlab prompt, type: help runpf
                            or: help runopf
                            or: help <name of any other m-file>


-----------
 THE FILES
-----------

Documentation files:
    README       - this file, basic description of MATPOWER
    CHANGES      - modification history of MATPOWER
    techinfo.pdf - PDF file describing the technical formulation of the
                   OPFs in MATPOWER (requires Adobe Acrobat Reader)

Input data files used by PF, OPF, UOPF:
    cdf2matp.m  - a stand-alone m-file which reads IEEE CDF formated
                  data and outputs data in MATPOWER's case.m format
    case.m      - same as case9.m
    case9.m     - a 3 generator, 9 bus case
    case30.m    - a 6 generator, 30 bus case
    case57.m    - IEEE 57-Bus case
    case118.m   - IEEE 118-Bus case
    case300.m   - IEEE 300-Bus case

Source files used by PF, OPF, UOPF:
    bustypes.m
    dSbus_dV.m
    ext2int.m
    idx_brch.m
    idx_bus.m
    idx_gen.m
    int2ext.m
    makeSbus.m
    makeYbus.m

Other source files used by PF (Newton-Raphson Power Flow):
    newtonpf.m
    pfsoln.m
    printpf.m
    runpf.m - main program for running a power flow

Other source files used by OPF (Optimal Power Flow):
    CCV.m
    dAbr_dV.m
    dSbr_dV.m
    idx_area.m
    idx_cost.m
    opf.m
    opfsoln.m
    printopf.m
    runopf.m - main program for running an optimal power flow
    totcost.m
    usesLP.m
    usesOT.m
    varVg.m
    The following are used only by the OPF algorithms based on
    Matlab's Optimization Toolbox:
        OTCCVfun.m
        OTCCVgra.m
        OTfungra.m
        OTopf.m
        OTSfun.m
        OTSgra.m
    The following are used only by the OPF algorithms based on
    linear programming:
        LPc_ld_d.m
        LPc_ld_s.m
        LPdense.m
        LPfslp_d.m
        LPfslp_s.m
        LPlpslvr.m
        LPopf.m
        LPtaskpa.m
        LPwchlps.m
        bp.m
        bpopt.m
        idx_lps.m
        loqo.m
        lp_solve.m
        sol_qps.m

Other source files used by UOPF (Combined Unit Commitment/OPF):
    (all files from OPF, except runopf.m)
    uopf.m
    runuopf.m - program for running an opf with the commitment heuristic


------------------
 OPF FORMULATIONS
------------------

The OPF methods based on Matlab's Optimization Toolbox consist of 3
basic methods, each of which has 2 variations (one with fixed generator
voltages, and one with varying generator voltages). The 3 basic methods
are ...

    1. STANDARD - method using polynomial cost function
    2. QCCV - method using quadratically constrained cost variables
    3. PLCCV - method using piece-wise linearly constrained cost vars

(The CCV methods are base on a constrained cost variable approach
suggested by Carlos Murillo.)

The code uses a numerical identifier for each algorithm, as follows:

    100 - Opt Tbx standard formulation, poly cost, fixed Vg
    101 - Opt Tbx standard formulation, poly cost, var Vg
    102 - Opt Tbx QCCV formulation, poly cost, fixed Vg
    103 - Opt Tbx QCCV formulation, poly cost, var Vg
    200 - Opt Tbx PLCCV formulation, p/w linear cost, fixed Vg
    201 - Opt Tbx PLCCV formulation, p/w linear cost, var Vg
    220 - Dense LP formulation, p/w linear cost, var Vg (lp.m solver)
    221 - Dense LP formulation, p/w linear cost, var Vg (bpmpd solver)
    222 - Dense LP formulation, p/w linear cost, var Vg (lp_solve solver)
    223 - Dense LP formulation, p/w linear cost, var Vg (loqo solver)
    224 - Dense LP formulation, p/w linear cost, var Vg (sol_qps solver)
    240 - Sparse LP formulation, p/w linear cost, var Vg (lp.m solver)
    241 - Sparse LP formulation, p/w linear cost, var Vg (bpmpd solver)
    242 - Sparse LP formulation, p/w linear cost, var Vg (lp_solve solver)
    243 - Sparse LP formulation, p/w linear cost, var Vg (loqo solver)
    244 - Sparse LP formulation, p/w linear cost, var Vg (sol_qps solver)

The default algorithm used given a polynomial cost function is 101 and
the default for piece-wise linear cost functions is 201.

The Optimization Toolbox (OT) based opf routines in this package are
based on the 'constr' function found in the Optimization Toolbox from
MathWorks. This uses a quasi-Newton method which does NOT exploit
sparsity, so it is rather slow except for small systems. The LP-based
methods can use several different LP solvers, including the one in the
OT (*VERY* slow). See the notes below regarding other solvers.

In the methods with fixed generator voltages, the free variables are the
voltage angles at all but the reference bus, the voltage magnitudes at
all non-generator buses, and the real and reactive power injections at
the generators. In the varying generator voltage methods, the voltage
magnitudes at the generators are also free to vary. In both cases, the
constraints are the power flow constraints, upper and lower limits on
voltage and real & reactive generator output, and apparent power flow
limits in the lines.

In the STANDARD methods, the objective function is just the summation of
polynomial cost functions for each generator. In the CCV methods, the
objective function is a simple summation of cost variables (one for each
generator). Each variable is constrained to lie above the generator cost
function via an additional quadratic inequality constraint in QCCV and a
set of linear inequality constraints in PLCCV.

The LP-based methods formulated identically to the PLCCV methods so the
solutions should match. The LP-based methods are documented further in
the file 'techinfo.pdf'.


---------------------------
 UNIT COMMITMENT HEURISTIC
---------------------------

In this code the unit commitment simply refers to a heuristic that is
used to determine whether or not to shut off an "expensive" generator as
opposed to operating it at it's lower limit (Pmin). The heuristic is
simple and could certainly be improved. The basic approach is to set
Pmin to zero for all of the generators and run an OPF. If any generators
are dispatched between 0 and their actual Pmin, then one of them is
selected and it is either shut down (set GEN_STATUS to 0) or forced to
be on and feasible (set Pmin back to actual value) and the procedure is
repeated, starting with re-running the OPF. When all generators are
dispatched between Pmin and Pmax the algorithm terminates.

The process of selecting which of the "infeasible" generators to make
"feasible" and how to decide whether to shut it down or enforce it's
Pmin limit goes as follows. If any generators are dispatched exactly at
zero, choose the one with the largest Kuhn-Tucker multiplier on its
Pg > 0 constraint. If none are exactly at zero, chose the one that's
"closest" to feasibility in a relative sense. That is, find the
generator with the smallest value of Pg/Pmin and the generator with the
smallest value of 1 - Pg/Pmin. Pick the smaller of the two and turn the
generator off if it was Pg/Pmin and turn it on with Pmin enforced if it
was 1 - Pg/Pmin.

The other rule that is used is that if shutting off a generator results
in a non-convergent OPF, the generator is turned back on with its Pmin
limit enforced.


------------------------
 LINEAR PROGRAM SOLVERS
------------------------

The LP-based OPF requires an LP-solver such as one of the following:

    bpmpd
        QP solver from http://www.sztaki.hu/~meszaros/bpmpd/ ($100)
        (MEX interface by Carlos Murillo <cem14@cornell.edu>)
    lp.m
        LP solver included with Optimization Toolbox (from MathWorks)
    lp_solve
        LP solver from ftp://ftp.ics.ele.tue.nl/pub/lp_solve/ (free)
    loqo
        LP solver from http://www.princeton.edu/~rvdb/ (free)
    sol_qps.m
        LP solver developed at U. of Wisconsin, not available)

None of the above are distributed with MATPOWER, however lp.m is
included in the Optimization Toolbox. This method is *VERY* slow. To use
one of the other solvers you will need to obtain the package from the
source listed above. Install it and delete the corresponding placeholder
file (bp.m, lp_solve.m, loqo.m, sol_qps.m) included in this
distribution. We have had best success with bpmpd.

More information about free optimizers is available in "Decision Tree
for Optimization Software" maintained by Mittenlmonn Hans and P.
Spellucci at http://plato.la.asu.edu/guide.html.


------------
 KNOWN BUGS
------------

First of all, please report any bugs you find to
Ray Zimmerman <rz10@cornell.edu>.

- 'area' is the name of an m-file in Matlab 5, my variable 'area'
  masks this m-file
