netlib/ieeecss/cascade/index

			 Cascade Software Availability
		    Cascade Version SUN0.9  June 23, 1988

Two groups of software are available under the cascade sublibrary of netlib.
These are the cascade subroutine library, and the cascade tools, which are a
group of programs which can be called either as subroutines or as commands 
from a Unix shell or VMS/DCL.  The main programs use routines from the 
subroutine library.

The cascade subroutine library's subroutines and functions are documented in
the manual "Cascade Library Users' Guide", available via netlib by requesting
"send cascade_users_guide.ps from cascade" in postscript form.

The cascade tools are documented in the manual "Cascade Tools and Knowledge
Base", available via netlib by requesting "send cascade_tools_and_kb.ps from
cascade" in postscript form.

These files, as well as a suite of examples, are also available as Unix
compressed tar-format files via anonymous login to hickory.engr.utk.edu at The
University of Tennessee, Knoxville.  If you are using a Unix system, the
Makefiles for libcascade.a (the cascade subroutine library) and
libcascadetools.a (the cascade tools library) are appended at the end of this
message; they will have to be modified to work at your site, since they are
intended to be invoked from the cascade distribution tape Makefile.

The network-available software is a part of the cascade expert system for
multivariable controller design using the LQG/LTR methodology.  The complete
distribution is available on Sun 1/4" (60Mbyte or 150Mbyte) or Sun 8mm tapes,
as a tar file, only.  The expert system requires the Quintus Prolog 
development environment for compilation and execution.  The cascade 
distribution tape and/or printed documentation is available from J. D.
Birdwell at the address below; a fee is charged to cover the cost of media 
and duplication.  The cascade expert system and tools are known to work only
on Sun 3 workstations at the present time.

No warranty is made concerning the quality of the cascade software or its
applicability.  The software available as a part of netlib has been placed in
the public domain by the authors, as a part of the cascade development 
project, sponsored by the U.S.  Department of Energy.  Several authors 
contributed to this project; they are cited in the manuals.

The cascade tools require several include files which netlib will not
automatically send; to receive them, request:
  send Parameter.f from cascade
  send dpcommon.f from cascade
  send dpcom.f from cascade
  send commands.h from cascade
You will also need the main program for the tools, headercode.c, in order
to invoke the tools from the command line:
  send headercode.c from cascade

For further information, contact:

  J. D. Birdwell
  Department of Electrical and Computer Engineering
  The University of Tennessee
  Knoxville, TN 37996-2100

  e-mail: birdwell@hickory.engr.utk.edu or birdwell@utkux1.bitnet

   ========================================================================

		  Contents of the Cascade Subroutine Library

			      Special Functions

file: ieeecss/cascade/ahcon.f
for: "ad-hoc" controllability calculation
file: ieeecss/cascade/gauss.f
for: Gaussian pseudo-random number generator
file: ieeecss/cascade/gfba.f
for: general frequency balancing algorithm
file: ieeecss/cascade/icnvrt.f
for: integer <-> character conversion
file: ieeecss/cascade/rand.f
for: uniformly distributed pseudo-random numbers on [0,1]
```
		    Regulator and Filter Design Software
```
file: ieeecss/cascade/ckbf.f
for: continuous time Kalman filter design program

file: ieeecss/cascade/creg.f

for: continuous time LQR design program


			   Riccati Equation Solver

The following routines comprise RICPACK, written by Arnold and Laub;
some of the code is based upon other work, as referenced in the
documentation.  the main entry points are ricsol and fbgain.

file: ieeecss/cascade/cmprs.f
for: forms a compressed matrix pencil for the GARE
file: ieeecss/cascade/exchqz.f
for: exchange diagonal blocks of the upper Hessenberg pencil a-s*b
file: ieeecss/cascade/fbgain.f
for: find the optimal gain from the GARE solution, discrete or conts
file: ieeecss/cascade/giv.f
for: forms a Givens rotation
file: ieeecss/cascade/newt.f
for: Newton iteration to GARE solution
file: ieeecss/cascade/order.f
for: reorders diagonal blocks of Hessenberg pencil a-s*b
file: ieeecss/cascade/resid.f
for: calculate GARE residual and its 1-norm
file: ieeecss/cascade/ricsol.f
for: calculates GARE solution, discrete or continuous time
file: ieeecss/cascade/rinv.f
for: used in solution to continuous time GARE
file: ieeecss/cascade/rotc.f
for: Givens rotation on columns
file: ieeecss/cascade/rotr.f
for: Givens rotation on rows
file: ieeecss/cascade/sepest.f
for: used to estimate condition
file: ieeecss/cascade/sequiv.f
for: used to form compressed problem
```
		       Frequency Response Computations
```
file: ieeecss/cascade/dfrmg.f
for: calculate frequency response at single frequency
file: ieeecss/cascade/dhetr.f
for: reduction of submatrix of real general matrix to up. Hess. form
file: ieeecss/cascade/zheco.f
for: lu factor & condition estimate of up. Hess. matrix
file: ieeecss/cascade/zhefa.f
for: lu factor of upper Hessenberg matrix
file: ieeecss/cascade/zhesl.f
for: solve complex upper Hessenberg system H*X=B
```
			 Matrix Exponential Routines
```
file: ieeecss/cascade/pade.f
for: calculate approx. of exp(a*t) and several integrals
file: ieeecss/cascade/pade8m.f
for: calculate approx. of exp(a)
```
		       Computation of Poles and Zeros
```
file: ieeecss/cascade/eigen.f
for: find eigenvalues and eigenvectors of real general matrix
file: ieeecss/cascade/housh.f
for: a Householder transformation
file: ieeecss/cascade/mvzero.f
for: computes finite multivariable zeros of a conts linear system
file: ieeecss/cascade/pivot.f
for: finds maximal element of vector and its location
file: ieeecss/cascade/rduce.f
for: extracts a reduced system with same transmission zeros
file: ieeecss/cascade/tr1.f
for: a Householder transformation
file: ieeecss/cascade/tr2.f
for: a Householder transformation
file: ieeecss/cascade/zeros.f
for: extract pencil defining zeros of original system
```
			  Ward's Balancing Routines
```
file: ieeecss/cascade/balgbk.f
for: back transform eigenvectors to original problem
file: ieeecss/cascade/balgen.f
for: balance generalized eigenproblem
file: ieeecss/cascade/balinv.f
for: inverse transformation of balanc (eispack)
file: ieeecss/cascade/gradbk.f
for: back transform eigenvectors from gradeq
file: ieeecss/cascade/gradeq.f
for: grade the submatrices of A and B
file: ieeecss/cascade/qzhesw.f
for: first step of QZ algorithm
file: ieeecss/cascade/qzitw.f
for: second step of QZ algorithm
file: ieeecss/cascade/reduce.f
for: reduce order of generalized eigenproblem if possible
file: ieeecss/cascade/scalbk.f
for: back transform from reduce and/or scaleg
file: ieeecss/cascade/scaleg.f
for: scale original problem
```
			  Lyapunov Equation Solvers
```
file: ieeecss/cascade/dstslv.f
for: solve A'*X*A - X = C, C symmetric & A up. RSF
file: ieeecss/cascade/lypcnd.f
for: solve F'*X + X*F + H = 0 by Bartels-Stewart
file: ieeecss/cascade/lypdsd.f
for: solve F'*X*F - X = H by modified Bartels-Stewart
file: ieeecss/cascade/symslv.f
for: solve A'*X + X*A + C = 0, C symmetrix & A up. RSF
file: ieeecss/cascade/hqrort.f
for: compute up. real Schur form (RSF); mod of HQR2
```
			   Linear Equation Solvers
```
file: ieeecss/cascade/gausel.f
for: Gaussian elimination
file: ieeecss/cascade/lineq.f
for: solves A*X=B for B a vector w/ cond. est.; uses dgecom and dgeslm
file: ieeecss/cascade/mlineq.f
for: solves A*X=B for B a matrix w/ cond. est.; uses dgecom and dgeslm
file: ieeecss/cascade/mpinv.f
for: calculate Moore-Penrose pseudo-inverse of real gen. A
```
			  Modified LINPACK Routines
```
file: ieeecss/cascade/dgecom.f
for: lu decomposition w/ cond. est.
file: ieeecss/cascade/dgefam.f
for: lu decomposition

file: ieeecss/cascade/dgeslm.f

for: solution of A*X=B using lu factors


			   Input / Output Routines

Note: see the Cascade Tools and Knowledge Base
manual (cascade_tools_and_kb.ps) for file formats.

file: ieeecss/cascade/insys.f
for: read a system container file
file: ieeecss/cascade/filext.f
for: modifies a file name by adding or changing an extension
file: ieeecss/cascade/fmout.f
for: formatted matrix output
file: ieeecss/cascade/mout.f
for: free format ascii matrix output
file: ieeecss/cascade/outsys.f
for: writes a system container file
```
		     Basic Matrix Manipulation Routines
```
file: ieeecss/cascade/cpycol.f
for: copy a column of a matrix (vector)
file: ieeecss/cascade/d1nrm.f
for: compute 1-norm of a matrix
file: ieeecss/cascade/dcl1.f
for: function to return 1-type magnitude of complex number
file: ieeecss/cascade/fnorm.f
for: compute Frobenius or Euclidean matrix norm of square matrix
file: ieeecss/cascade/madd.f
for: matrix addition
file: ieeecss/cascade/mmul.f
for: matrix multiplication
file: ieeecss/cascade/mqf.f
for: symmetric matrix product, X'*S*X
file: ieeecss/cascade/mqfa.f
for: symmetric matrix product, X'*X
file: ieeecss/cascade/mqfwo.f
for: symmetric matrix product, X'*S*X, stored in S
file: ieeecss/cascade/mscale.f
for: scalar matrix product, a*X
file: ieeecss/cascade/msub.f
for: matrix subtraction
file: ieeecss/cascade/mula.f
for: matrix product, A*B, stored in A
file: ieeecss/cascade/mulb.f
for: matrix product, A*B, stored in B
file: ieeecss/cascade/mulwoa.f
for: matrix product, A*B, stored in A
file: ieeecss/cascade/mulwob.f
for: matrix product, A*B, stored in B
file: ieeecss/cascade/save.f
for: copy a matrix
file: ieeecss/cascade/symprd.f
for: symmetric matrix product, X'*A*X
file: ieeecss/cascade/trnata.f
for: replace a matrix in an array with its transpose (in place)
file: ieeecss/cascade/trnatb.f
for: form matrix transpose
file: ieeecss/cascade/xty.f
for: matrix product, X'*Y
file: ieeecss/cascade/xyt.f
for: matrix product, X*Y'

file: ieeecss/cascade/zl1nrm.f

for: compute 1-norm of complex vector and scale vector by its norm


========================================================================

			      The Cascade Tools

Note:  These tools are intended primarily for use by the cascade expert 
system, which implements a version of the LQG/LTR multivariable controller 
design methodology.  All of the tools can be run from the Unix or VMS/DCL 
command line, but some are not very useful except to the expert system.  The
tools can also be called as subroutines in other programs.  As commands, all
the tools expect command line arguments providing parameters and necessary 
files.  These are provided as elements of the argument lists when the tools 
are accessed as subroutines.  File formats and the command line formats are 
described in the manual.  All the tools require several include files in 
order to compile, which define limits on array and matrix sizes and other 
parameters.  The tool contained in the file "svplot.f" requires the cgs/ncar
graphics library, but can be modified to use any low-order line graphics 
library.

The tools all use a common command line parser, contained in the file
"headercode.c".  The commands to be built into headercode are defined in
"commands.h", included in headercode.c.  There is currently a problem with 
this code's execution on Sun 4 machines.  If you wish the patch when it 
becomes available, contact J.  D.  Birdwell, birdwell@hickory.engr.utk.edu.
Notification will be available only via e-mail.  The tools are linked with
headercode.c into one large file, and, on Unix, links are defined from the
toolname (e.g.  aolsys) to the headercode executable.  Which tool is to be
executed is determined by the name of this link.  On VMS systems, a command
definition file is required; contact J.  D.  Birdwell for its availability.
The tools were originally developed under a VMS/DCL environment, but have 
since been ported to Unix The command line software may or may not work 
under recent releases of VMS; it has not been tested.

headercode.c  main program used to access all tools from the command line

file: ieeecss/cascade/aolsys.f
for: Analyze Open Loop System
file: ieeecss/cascade/auginp.f
for: Augment at Input
file: ieeecss/cascade/augout.f
for: Augment at Output
file: ieeecss/cascade/augsqr.f
for: Augment-Square
file: ieeecss/cascade/balsvd.f
for: Balance Singular Values
file: ieeecss/cascade/dlohi.f
for: Decide Low or High
file: ieeecss/cascade/evlbnd.f
for: Evaluate Bounds
file: ieeecss/cascade/exmsys.f
for: Examine System
file: ieeecss/cascade/kbf.f
for: KBF
file: ieeecss/cascade/kbffwc.f
for: KBF Find Wcmin
file: ieeecss/cascade/lqr.f
for: LQR
file: ieeecss/cascade/lqrfwc.f
for: LQR Find Wcmin
file: ieeecss/cascade/ltrkbf.f
for: LTR using KBF
file: ieeecss/cascade/ltrlqr.f
for: LTR using LQR
file: ieeecss/cascade/makbnd.f
for: Make Bounds
file: ieeecss/cascade/makmat.f
for: Make Matrices
file: ieeecss/cascade/rankv.f
for: Rank of V
file: ieeecss/cascade/svplot.f
for: Svplot and Bounds
index help

Eric and Jack