 Using csc

Table of Contents

Section 1.  Introduction

Section 2.  Data Inputs

Section 3.  Interpreting results

Section 4.  Building csc


Section 1.  Introduction
------------------------

csc is run from the command line.  Following the build directions given below,
and assuming we are currently in the "runs" directory, csc is invoked by the
command:

../bin/csc cscdirs

Here, "cscdirs" is a "directions" file, which points to a 
configurations file, which points to the actual data files (such as the network
file) to be used in the simulation.

Section 2.  Data Inputs
------------------------

Data inputs to csc are organized hierarchichally.  First, there is a "directions" file which is the sole input to csc on the command line.  In basic use of csc
the directions file is used to specify a "configuration" file, which in turn,
is used to specify a variety of input parameters and input data files.  

These data files principally include:

* A network file which specifies the topology of the grid, including line
  reactances, line limits, nominal loads and generator limits (example, below).

* A bus injection/extraction file.  This file provides a list of buses, and,
  for each such bus, a value between 0 and 1.  These values are interpreted as
  follows: if the bus is a generator, the fraction indicates the proportion of
  the maximum output of the generator to be used.  If the bus is not a generator
  the fraction indicates the fraction of the nominal load to be used.  If a 
  bus is not listed in the file, it is assumed that the fraction is zero.

* A contingency ("scenario") file.  This file provides a list of lines that
  will be removed (tripped) as the first step of the simulation.  The list
  may be empty.

* A control file.  This file specifies an affine control to be used to shed
  load as the cascade unfolds.  In basic use of csc, this file will indicate
  that no load shedding will be applied.

Configuration file.
==================

An example of a configuration file follows:

+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-

dataname path3.dat

initialb solpath3.dat 

readscenarios scen_01

usecontrol nocontrol_perround.dat 

alpha 1.0

maxrounds 10

replevel 0.01

seed 99999

LPalgorithm barriernox

detailmode quick 

flowmodel linear exact

strictloadnotrequired 

END

+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-

This configuration file indicates that the network file is "path3.dat", the
injection/extraction file is "solpath3.dat" and the scenario file is "scen_01",
the control file is "nocontrol_perround.dat".  Further, it indicates an "alpha"
parameter of 1.0 and that the (maximum) number of rounds equals 10. The 
"replevel" value of 0.01 indicates that a certain amount of output will be
produced (a negative value will supress output).  The "seed" value is a 
random seed.  The "LPalgorithm" setting indicates that all linear programs
will be solved using the barrier algorithm without crossover (the recommended
setting).  All other entries in the configuration file should be left as 
given above.  Finally, the "END" is required.

Network file.
============

An example of a configuration file follows:

+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-

3 2

0 1 1.0 100 0
1 2 1.0 200 0

generators 2

0 90 0
2 200 0

loads 1

1 190

END

+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-

The blank lines are optional.  The first line of input indicates a network with
three buses and two lines.  For each of the two lines, there is a line in
the file describing, respectively, the "from" bus, the "to" bus, the line
reactance, the line limit, and an additional field that is not read by csc but
must be present.  For example, the first line is described by 

0 1 1.0 100 0

which states that the from bus is 0, the to bus is 1, the line reactance is
1.0 and the limit is 100.  IMPORTANT NOTE: all buses are labeled starting at
zero.

The file then indicates that there are two generators.  Following this we have,
for each generator, the bus housing the generator, the maximum output and
an additional field that is not read by csc but must be present.

Next, the file indicates the number of loads, and for each load the corresponding bus and the nominal value for that load.  

Finally, the "END" statement must be included.

Bus injection/extraction file.
=============================

The following is an example of such a file; which corresponds to the network
file given above:

+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
d0 = 1.0
d1 = 1.0
d2 = 0.5

END
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-

The file indicates, for each bus, the fraction of generation or demand that
is used for a given case.  In the above example, since bus 0 is a generator,
it specifies that 100% of the maximum output of that generator (in the 
above example, 90 units) will be used.  Likewise, since bus 2 is a generator
the file specifies that half of that generator's maximum output will be used,
that is to say, 0.5*200 = 100 units.  Finally, the file indicates that in
the case of bus 1, which is a load, 100% of its nominal demand will be used,
i.e. 190 units.  

In consequence, a total of 190 units of generation are specified, and 190 
units of demand are specified.  IMPORTANT:  total generation must *exactly*
match total demand.

Scenario file.
=============

An example of a scenario file is the following:

+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
1
xxx outages: 1
line 0: 0 1
END
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
The first line indicates a scenario applies.
The next line indicates that in this scenario one line will be tripped, and
that this is line 0 (which has "from" bus 0 and "to" bus 1).  IMPORTANT: the
specific syntax indicated in the example is needed.  The END at the end of 
the file is required.

If no scenario applies, the first line should be a '0'.  This must be followed
by a single line of text containing the "END".

Control file.
============

Here is an example of a control file:

+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-

componentwise_piecewise_uniform
tempo perround 
numpieces 1
1 everyload 

  1 1 1 0
  andforever

END

+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-

The critical data in this file are the two consecutive lines 

  1 1 1 0
  andforever

This indicates that on round 1 (the first round) a (c,b,s) control with 
values (1,1,0) will be applied, and that for every round thereafter, the 
same control will likewise be used.  Since a (1,1,0) control does not shed
any load, csc will therefore simulate an uncontrolled cascade.

Directions file.
===============

A typical directions file follows:

+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-

cscconfig config.dat  END

+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-

This indicates that configuration file "config.dat" is to be used.  The END
at the end is mandatory.

Section 3.  Interpreting results
--------------------------------

csc will output results to the command-line, and also to a file named "csc.log".
Using the above numerical examples, the critical information appears toward
the end of the file:

************************************************

           RUN SUMMARY

yield: 6.3158e-01

************************************************

which indicates that at the end of the cascade, a fraction of .63158 of the 
total initial load is being satisfied.  The file also includes per-round
information (current yield, number of line trips).  In the above example,
the cascade terminates after one round, with no faults.  


It is easy to generate additional, extensive output.  Please consult the author.


Section 4.  Building csc.
-------------------------

csc is written in the C language.  It uses the Unix sockets library, though this
requirement can be bypassed (consult the author) and it is possible to 
build csc under Windows.  The remainder of this section assumes a Unix-type
environment.

In order to build csc, either Gurobi or Cplex must be linked with.  In the src
directory, modify the makefile as follows:

1. In the LPSOVER section, choose the appropriate CCLNFLAGS line (comment out
the other).

2. If using gurobi, in the GUROBI section appropriately set the GRB and 
GRBLNFLAGS variables.  Also, place a copy of the appropriate gurobi_c.h 
file in the src directory.


3. If using cplex, in the CPLEX section appropriately set the CPX variable. 
Also, place a copy of the appropriate cplex.h file in the src directory.


Having made these changes, issue (from the src directory):

make csc_versioned

If successful, this will result in all binaries, including csc, being placed in
the bin directory.



