Realization of feedback laws computed by Pieri homotopies in PHCv2.4.87

Run "gprbuild feedback.gpr" to make all test programs.
On windows, type "gprbuild feedback.gpr -Xos=windows"
at the PowerShell prompt.
The "gprclean feedback.gpr" removes all files created by gprbuild.
On windows, add the "-Xos=windows" at the end of the gprclean command.

Software to realize the application of Pieri homotopies
   to find dynamic compensators for linear systems

   Organization of the software   
----------------------------------------------------------------------
We distinguish three levels in the development of portable
and self-contained C software:

(1) the basics
     + complex arithmetic : dcmplx
     + polynomial arithmetic : poly_dcmplx, append_polymatrix
     + linear algebra routines : dc_matrix, dc_inverse, append_dcmatrix
     + roots of a univariate polynomial : dc_roots
     + Newton interpolation : dc_interpolation
(2) numerical Smith normal form
     + numerical greatest common divisor : poly_gcd
     + matrices of univariate polynomials : poly_matrix, poly_hermite
     + Smith normal form function : poly_smith
(3) format conversions and realization 
     + convert matrix from C format to Ada format:
       c2ada_dc_matrix, c2ada_poly_matrix
     + convert matrix from Ada format to C format:
       ada2c_poly_matrix(in pieri_sols)
     + Pieri homotopies give transfer function
       and state-space realization :  realization

The software of level (1) is tailored towards our specific
application.  We include it to make our software self-contained.
At level (2) we present an original algorithm to calculate the
Smith normal form of a matrix of univariate polynomials with
approximate complex coefficients.  While realization algorithms
are our prime target, our numerical Smith algorithm might be of
independent interest.  The C functions at level (3) deal with 
two format conversions. "Give transfer function" is specific 
for the localization patterns of the Pieri homotopy algorithm.
The numerical realization routine is thus again of general interest.
Finally, a MATLAB script is written for verifying the results by 
comparing the computed poles with the given poles and finding the 
condition number for each given pole.

A detailed description of the software is given below.
Test programs start with "ts_" and can be created via the makefile.
The main test program is "ts_feedback" and is created in the main
Objects directory of PHCpack, see below for more information.

------------------------------------------------------------------------------
file name                 : short description
------------------------------------------------------------------------------
dcmplx                    : defines complex numbers of double floats
ts_dcmplx                 : interactive testing of complex arithmetic
dc_roots                  : approximates all roots of a polynomial
ts_roots                  : tests root finding operations
dc_matrix                 : defines basic operations on complex matrices
append_dcmatrix           : appends to complex matrix, row or columnwise
ts_dc_determinant         : tests calculation of determinant of matrix
dc_inverse                : inverse of a complex matrix
ts_dc_inverse             : test on inverse computation
------------------------------------------------------------------------------
poly_dcmplx               : arithmetic of complex polynomials
dc_interpolation          : interpolation with divided differences
poly_gcd                  : defines extended gcd calculations
ts_interpolation          : tests interpolation routines
ts_gcd                    : tests gcd computations
poly_matrix               : defines operations on matrices of polynomials
append_polymatrix         : append to polynomial matrix, row or columnwise
poly_hermite              : Hermite normal form of polynomial matrix
poly_smith                : Smith normal form of polynomial matrix
ts_hermite                : test on the Hermite normal form
ts_smith                  : test on the Smith normal form
ts_multiply               : test on polynomial multiplication
ts_divide                 : test on poly_divide in poly_smith
ts_poly_inverse           : test on inverse of polynomial matrix
------------------------------------------------------------------------------
c2ada_dc_matrix           : converts complex matrix from C to Ada format
c2ada_poly_matrix         : converts polynomial matrix from C to Ada format
ts_c2ada                  : tests format conversions
read_input                : prepares input for Ada code
realization               : defines the realization algorithms
ts_realization            : test on the realization algorithms
pieri_sols                : processing output of Pieri homotopies
timer                     : time the duration of the calculation
ts_timer                  : tests if timer gives the correct result
ts_feedback               : main test on dynamic output feedback
ts_explore_Cpoles         : exploration of reality issues
ts_explore_poles          : exploration of reality issues
------------------------------------------------------------------------------
v_perm                    : MATLAB script to reorder eigenvectors
v_pole                    : MATLAB script for difference between poles
verify                    : MATLAB script to verify output of programs
------------------------------------------------------------------------------

----------------------------------------------------------------------
    Find feedback laws of a given system
----------------------------------------------------------------------
(1) generate an executable file (current directory is "Feedback" directory)
     + change to "Objects" directory:  cd ../Objects
     + generate the executable file ts_feedback:  make ts_feedback
       (by default, the executable file is in ../bin directory)     
(2) run the executable file
     + go back to "Feedback" directory: cd ../Feedback
     + ts_feedback can be executed like this:
         ../bin/ts_feedback input_file  output_file     
       to run an example:  ../bin/ts_feedback Data/app_sate Data/output
     + the feedback laws can be found in "Data/output"
(3) verify with MATLAB (optional)
     + copy output_file to verify_data.m: cp Data/output verify_data.m
       (verify_data.m is called by verify.m as the input data)
     + load MATLAB
     + set the current directory as "Feedback"
     + type "verify" at the command line

-----------------------------------------------------------------------
   Information to be provided in the "input_file"
-----------------------------------------------------------------------  
In the input file, the following information needs to be provided:
The number of the internal states for the given plant (A, B, C) n,
The system's input dimension m,
The system's output dimension p,
The number of the internal states for the dynamic compensators q,
The number of maps(solutions) wanted (<0 for all), 

Type 0, 1, 2, or 3 to select output level :
  0. no intermediate output;
  1. only final determinant validation;
  2. + validation of all intermediate determinants;
  3. + intermediate output of all path trackers.

Type 0, 1, 2 to select input :
  0. interactive input of real numbers
  1. interactive input of complex numbers
  2. random input of complex numbers
  3. random input of real numbers
  4. interactive input of real numbers for 
     matrices and complex numbers for poles

The A, B, C matrices of the given plant, 
Give n+q poles for the closed loop system.

Examples of input and output data can be found in "./Data" directory

--------------------------------------------------------------------------
    Test a subroutine
--------------------------------------------------------------------------
(1) generate an executable file (current directory is "Feedback" directory)
     + make the object in the makefile in the "Feedback" directory 
       (see the makefile to change default destination of executables)
       e.g., to generate a test file for realization: make ts_realization
(2) run the test file
     + test_file < input_file  or  just test_file with interactive input
       to run an example:  ../bin/ts_realization < Data/realization

Examples of test data can be found in "./Data" directory 
--------------------------------------------------------------------------

    A note about the prefixes:
--------------------------------------------------------------------------
   dc = double complex
   ts = test facility
 poly = one variable polynomial
--------------------------------------------------------------------------

   Convention for printing or reading a polynomial
-------------------------------------------------------------------------- 
From the low degree to the high degree coefficient
--------------------------------------------------------------------------
