Introduction to ExactModeling
=============================
Author: M. Rickli, Automatic Control Lab, ETHZ
Zurich, Switzerland
rickli@aut.ee.ethz.ch
Version: 1.0, June 96 for Mathematica v2.2 or higher
FTP: ExactModeling is available by anonymous ftp from
ftp://aut.ee.ethz.ch/pub/personal/rickli
Copyright: Copyright by M. Rickli, Automatic Control Lab, ETH Zurich
All files may be used, copied, modified and distributed
freely provided this copyright notice is preserved. The software
may not, however, be sold or distributed for profit
without written permission of the author.
Purpose
-------
ExactModeling is a Mathematica package providing algorithms for exact
identification of linear time invariant dynamical models. It is based
on the theory of behavioural modelling developed by J. Willems and
A. C. Antoulas.
The package is split in two files:
- ExactModeling.m
- EMUtils.m
Both files are needed and should be installed in the same location.
As with every package in Mathematica before using any of the defined
symbols it must be loaded:
< prec.
If a precision is chosen greater than $MachinePrecision (usually 16),
every element of an input argument must have at least precision prec.
Setting WorkingPrecision -> Infinity results in exact calculations. All
elements must then be exact numbers (in the sense of Mathematica! Thus
Sqrt[2] or Pi are not allowed).
Functions
---------
Following we give a short description of all functions in the context
ExactModeling`.
n = Complexity[data, lam, noiselevel]
Returns (minimal) number of data points necessary to find a theta model
explaining data. Tests last singular value of rows of an observability
matrix to be smaller than noiselevel.
See: A. C. Antoulas, optimal inputs for identification, 1996.
{P, gamma, Psort, thnew} = ProcessNewMeasurement[th,data,lam,var,options]
Calculates the new model thnew which results from updating th with a
new time series w = data exp(lam t).
thnew = Dot[Psort, gamma, P, th]
In case of polynomial time data the function calls itself recursively
with a related time series.
For correct results th should be a MPUM (C-MCUM) and index set I be set
correctly (-> SetControlSet).
A return value of $Failed indicates an error during calculations -> pre-
vious state restored, thnew = th.
Aliases: PNM
thnew = MarkovModel[data,var,opts]
Computes a model thnew from given Markov parameters (impulse response
data) 'data'.
For SISO system 'data' is a vector: {h(0),h(1),h(2), ..}
For MIMO system 'data' is a sequence of matrices: A(0),A(1),A(2), ..
thnew = RatInt[zlam,lam,var,opts]
Calculates the MPUM thnew which corresponds to (frequency response)
measurements {lam,zlam}.
Several input formats are possible: (lam always a vector)
RatInt[glam,lam,var,opts] for SISO systems (glam a vector)
RatInt[zlam,lam,var,opts] for MIMO systems (zlam a sequence of matrices)
RatInt[{zlam},lam,var,opts] zlam given as list of matrices, where
#col(zlam) = #inputs;
#matrices(zlam) = Length(lam).
Aliases: RationalInterpolation
thnew = RatInt[theta0,{zlam},lam,var,opts]
Starts modeling procedure with (MPUM) theta0. Before using this form
the internal state must coorespond to theta0; -> InitializeExactModeling,
-> SetState.
Aliases: RationalInterpolation
thnew = TF2Theta[tf,lam,var,opts]
Finds a model thnew explaining transfer function tf at frequencies lam.
tf can be a pure function or an expression in var.
MIMO transfer matrices are supported.
TF2Theta may be used as transformation from transfer function to theta
model representation.
See also: CalculateTransferMatrix.
tf = CalculateTransferMatrix[theta,index,var]
Returns transfer matrix G[var] = Inv[T].Q, where theta = [Q | -T].
This corresponds to the I/O model of theta.
index specifies set of controllable rows (optional).
Aliases: CTM
tf = ProperTransferMatrix[theta,index,var,opts]
Returns a proper transfer matrix of theta.
index specifies set of controllable rows (optional).
Currently only for SISO systems implemented (i.e. Dimensions[theta] = {2,2} ).
eps = CalculateError[th,p,lam,(var)]
Returns vector of error time-polynomials without factor Exp[lam t].
Error: e(t) = th(d/dt) p(t) Exp[lam t] = eps Exp[lam t]
CheckMeasurement[th,data,lam]
Tests if controllable model is affected by this measurement.
Returns True if calculations should proceed.
InitializeExactModeling[lam,var,cset,conjcomplex,opts]
Sets internal state of ExactModeling such that calculations may start/proceed
with 'arbitrary' theta0 (specified by lam and cset).
The list of frequencies lam equals the zeros of det(theta0) and the number of
frequencies in lam equals the sum of row degrees of theta0.
List cset specifies the controllable rows of theta0.
lam may contain single (complex) frequencies lam_i and/or multiple entries
(entered as {lam_i, count}).
If conjcomplex is True the conjugate values of all complex frequencies in lam
are considered as well.
Aliases: InitEM
ShowExactModeling[] displays all internal variables with their actual values.
{f,b} = GetUpdateMatrices[k]
Returns f = (u_n ... u_k+1) and b = (u_k ... u_1) where u_i are update
matrices at step i (u_i = Psort.Gamma.P).
Returns {$Failed, $Failed} if integer k is out of valid range {1,n-1}.
Matrices f and b may only be calculated if storing of update matrices
is active (StoreResults[True]).
SavePrefs["file"]
Saves actual settings of ExactModeling to "file" in your current working
directory. Settings may be loaded using LoadPrefs["file"].
SavePrefs["file", UserSymbols]
Allows to save settings together with definitions of other symbols.
LoadPrefs["file"] loads settings of ExactModeling from "file".
{M, thnew} = TriangularizeModel[th, var, opts]
Returns unimodular matrix M and thnew, such that leading coefficient matrix of
thnew is in 'upper' triangular form (row permutation may be necessary).
First coefficient of highest degree term in each row is normalized to 1.
This algorithm should also work for singular (square) matrices.
Aliases: NormHRC
M = PowerReduce[th,{index},var]
Returns matrix M which eliminates highest coefficient in first column of th by
applying a linear combination of both rows.
Both rows must have same row degree. SISO only!
ResetExactModeling[varname,controlset,options] resets all internal
variables to their default values. Options are not changed unless new
settings in argument options are specified.
SetEMDefaultOptions[opts] may be used to overwrite the default setting of
options in ExactModeling.
SetMode[action] tells the system how to continue calculations.
Possible settings for 'action' are:
Ask : Ask user what to do ;-)
None : Do not process data with no relevant information
All : Process all input data
SetControlSet[cset]
Specifies set of row indices building the controllable part of the model.
cset = GetControlSet[]
Returns sorted list of row indices building the controllable part of the model.
SetState[dump] sets internal data to continue calculations. See GetState[dump].
dump = GetState[]
Returns all internal data necessary to proceed calculations later.
SetVariableName[newname] sets the name of the placeholder variable to 'newname'.
var = GetVariableName[] returns the name of the placeholder variable.
StoreResults[boolean] enables/disables storing of all update matrices.
hrc = LeadingCoefficientMatrix[m, var]
Returns the highest-row-degree coefficient matrix of polynomial matrix m.
If this matrix is non-singular the matrix m is row reduced (see Kailath p 384).
w1 = RelatedTimeSeries[p,lam,time]
Returns a related time series (eq. 4.1 in Ant_Paper)
w_n,1 = (d/dtime - lam) ( p(time)Exp(lam time) ) = w1 Exp(lam time).
rd = RowDeg[expr,var]
Returns the row degrees of the polynomial Matrix expr with indeterminate var.
RowReducedQ[m, var]
Returns True if polynomial matrix m(var) is row reduced, i.e. its leading
coefficient matrix has full row rank.
Options
-------
The following (named) options are defined for use in this package with
their default settings:
Method -> Gauss NoiseLevel -> 0
Normalize -> Automatic PrintFunction -> Factor
Sorting -> MaxDifference WorkingPrecision -> 16
Method determines transformation of the error vector to normalized form.
Method -> Orthogonal uses a housholder matrix.
Method -> Gauss uses simple pivoting strategy.
NoiseLevel -> level specifies an _absolute_ bound below of which entries in
an error vector are set to zero.
Normalize -> AnyFunName specifies function AnyFunName to be applied to theta
after a recursive update. This may be used to transform theta to a special
form, e.g. normalize coefficients or factor elements of theta.
Care must be taken to preserve the set of controllable rows!
AnyFunName must conform the calling convention:
{P,(P.theta)} = AnyFunName[theta_, var_Symbol, options___Rule].
PrintFlag -> True may be used to see (internal) progress information. This
option was introduced for debugging.
PrintFunction -> AFunc specifies function AFunc to be applied to theta
for printing in the summary information. This options applies
only for the case PrintLevel -> 5 and does not affect theta.
PrintLevel -> value specifies the amount of progress information shown
during calculation. Possible values:
0 no intermediate results are shown (Default)
2 minimal progress info
3 frequency, measurement, error and thnew
5 all results of the last update step and PrintFunction[thnew]
9 all results of the last update and transfer function
Sorting -> method may be used in RatInt, TF2Theta and SortFrequencies to
sort data in a specific order.
Possible settings are None, Linear, MaxDifference or MaxError.
Linear sorts in ascending order.
MaxDifference maximizes difference of adjacent elements (frequencies).
MaxError sorts difference in transfer function between model and data
in descending order.
VectorNorm -> True indicates to apply a relative error bound to
determine elements near zero, otherwise an absolute bound
10^(-WorkingPrecision+WPOffset) is used.
This option affects vectors only.
WorkingPrecision -> n specifies how many digits of precision should
be maintained in internal computations. WorkingPrecision -> n causes
all internal computations to be done to at most n-digit precision.
Settings
--------
Most settings are integrated as (named) options and are always
optional input arguments (see below).
As mentioned above, the indeterminate variable may be specified using
argument var where appropriate. We suggest to specify var at least for
every new model to be computed (its value will be saved internally).
Otherwise symbol ExactModeling`VarName will be used.
Some global settings, which might be changed occasionally, may be
accessed through functions. These are
SetMode[action]
allowed settings for action are: Ask, None, All
Some calculations need user interaction, e.g. new data does not
change the controllable model. In this case action specifies if
a dialog box is shown needing user input (Ask)
calculations are skipped (None)
calculations proceed in any case (All).
StoreResults[boolean]
For later reference all update matrices are stored internally.
In case of limited storage or speed concerns this feature may
(temporarily) be turned off (StoreResults[False]).
SetEMDefaultOptions[opts]
Changes the default settings of all (named) options, which by
itself are stored in variable EMDefaultOptions.
SetVariableName[newname]
change the actual setting of indeterminate variable var.
This functionality is also offered by every function involving a
model.