Proposed for review

ss_model - Implement a state space model

## Synopsis

State-space model form
object ss_model {
form OCF|CCF;
timestep time s;
A "a00 ... a0N ; ... ; aN0 ... aNN";
B "b00 ... b0M ; ... ; bN0 ... bNM";
C "c00 ... c0M ";
D "d00";
x "ref1 ref2 ... refN";
u "input1 input2 ... inputN";
y "output";
}

Transfer function model form
object ss_model {
form OCF|CCF;
timestep time s;
Y "bN ... b0";
U "aN ... a0";
x "ref1 ref2 ... refN";
u "input1 input2 ... inputN";
y "output";
}

Differential model form
object ss_model {
form OCF|CCF;
timestep time s;
Q "a0 .. aN";
U "b0 .. bN";
x "ref1 ref2 ... refN";
u "input1 input2 ... inputN";
y "output";
}


## Description

The state space model of the form

$\dot x=Ax+Bu ; y=Cx+Du$

is constructed from a transfer function of the form

$H(s)=\frac{Y(s)}{U(s)}=\frac{\sum_{n=0}^N{b_n s^{N-n}}}{\sum_{n=0}^N{a_n s^{N-n}}}$.

Two possible conversions are supported: the canonical controllable form

$A=[TODO] ; B=[TODO] ; C=[TODO] ; D=[TODO]$

and the canonical observable form

$A=\begin{bmatrix} -a_1 & 1 & 0 & \cdots & 0 \\ -a_2 & 0 & 1 & 0 & 0 \\ \vdots & \vdots & 0 & \ddots & \vdots \\ -a_{n-1} & 0 & 0 & \cdots & 1 \\ -a_n & 0 & 0 & \cdots & 0 \end{bmatrix}; B=\begin{bmatrix} b_1 - a_1 b_0 \\ b_2 - a_2 b_0 \\ \vdots \\ b_{n-1} - a_{n-1} b_0 \\ b_n - a_n b_0 \end{bmatrix}; C=\begin{bmatrix} 1 & 0 & \cdots & 0 \end{bmatrix}; D=b_0$

## Properties

### form

The form property describes the canonical form of the state space model. The model can either be in controllable form (CCF) or in observable form (OCF).

#### CCF

CCF is used to specify the controllable canonical form for the state space model.

#### OCF

OCF is used to specify the observable canonical form for the state space model.

### timestep

Specifies the timestep uses when updating the state space model. The default unit is in seconds.

### Y

Specifies the numerator of the transfer function used to define the state space model. This should be specified as a space-separated list of values from highest to lowest order, e.g., "$b_n\ b_{n-1}\ \cdots\ b_0$".

### U

Specifies the denominator of the transfer function used to define the state space model. This should be specified as a space-separated list of values from highest to lowest order, e.g., "$a_n\ a_{n-1}\ \cdots\ a_0$".

### Q

Specifies the coefficients of the differential form used to define the state space model. This should be specified as a space-separated list of values from lowest to highest order, with the input coefficient appended separated by a comma, e.g., "$a_1\ a_2\ \cdots\ a_n\ ,\ b_0$".

### x

Specifies the state vector as either a list of initial values (hidden variables) or a list of references to object properties.

### u

Specifies the control vector as a list of references to object properties.

### y

Specifies the output vector as a list of references to object properties.

## Example

Set up the clock (this always should be done):

clock {
timezone PST+8PDT;
starttime '2000-01-01 00:00:00 PST';
stoptime '2000-01-02 00:00:00 PST';
}


Load the tape model, define the test target class, and instantiate one test object:

module tape;
class test {
randomvar x;
double u;
double y;
}
object test {
name test;
x "type:normal(0,1); integrate; refresh:1min";
object recorder {
file "test_w.csv";
property "x,u,y";
interval 60;
};
}


Load the control module, and apply a state-space model to the test object:

module control;
object ss_model {
form OCF;
timestep 1 min;
Y "1 1";
U "1 1";
x "0 0";
u "test.x test.u";
y "test.y";
}


## Bugs

Only single output forms are supported.

## Version

The Controls module is available only in McNary (trunk).