How to use LinSys.dll for Veritak

1. Introduction

A state space description of a linear system is an easy way to define and calculate (approximate) systems of any order with multiple inputs and outputs.
The idea behind this is to describe the system in a set of simple differential equations, written as matrices.

Every differential equations describes the dx/dt of one state variable, this differential can be a function of all other state variables and/or the inputs of the system.
For calculating the outputs of the system, the state variables are used and/or the inputs.

A state variable can be seen as an energy storage element in the system ( or like something that depends on the history of the system). Examples of this if for example a capacitor in an electronic circuit.
2. Description of the system

The formula looks like this :

dX/dt = A.X + B.U
Y       = C.X + D.U

where dX/dt is a column vector
X = a column vector with the values of the current state
Y = a column vector with the outputs of the system
U = a column vector with the input values

A = the state matrix  (n x n)
B = the input matrix  (n x p)
C = the output matrix (q x n)
D = the feedforward matrix (q x p)

n = the degree of the system (so e second order system has a 2 by 2 system matrix)
p = the number of inputs
q = the number of outputs

The intention is to approximate the Y values after an interval DeltaT. First the runge-kutta method is used to solve the first equation, with the new X vector, the output can be calculated. The X vector is stored for the next iteration.

Example : second order RLC circuit

Vin -----L---------- Vout
|     |
C    R
|     |
0V------------------

As states we chose the voltage on the capacitor C (x1) and he current through the inductor L (x2).

We can derive following :

dVc/dt = Ic / C = (Il - Vout/R)/C

dIl/dt = Vl / L = (Vin - Vout)/L

or using the defined states (and Vc = Vout):

dx1/dt = -x1/(R.C)+x2
dx2/dt = -x2/L  + Vin/L
Vout = x1

So these are the matrices :

( -1/(R.C)       1/C )                (    0   )
dX/dt =    (                            )      X  +   (         )    Vin
( 0                  -1/L)                (   1/L )

Y  =   ( 1     0 ) X + 0 Vin

The values of the A B C D matrix have to be in a file in the correct order (first A, then B, ...). The file is parsed and the order of the system, the number of inputs and outputs is automatically determined.

You can write the file manually, or generate the matrices with matlab. The tf2ss function converts a transfert function into the A B C and D matrix. Writing them into a file that can be read by the LinSyS dll goes like this :

[A B C D] = tf2ss(num, den)
save 'filename' A B C D -double -ascii
3. vpi interface

In general a system must be initialized (for example in an initial block), and will be calculated repeatedly in an always block.

To initialize a system, 3 functions are foreseen : \$LinSys_SisoInit, \$LinSys_MisoInit, \$LinSys_MimoInit. As evident, a MIMO system can also be used for example for a SISO and MISO, the difference is mostly how the calculation function must be called.

For the calculation itself : \$LinSys_SisoCalc, \$LinSys_MisoCalc, \$LinSys_MimoCalc.

Special functions are foreseen for reading and writing the state variable, or coping the internal state to another system : \$LinSys_GetState, \$LinSys_SetState, \$LinSys_CopyState.

4. Initialization

Id = \$LinSys_SisoInit(filename, [state_array]) : initialises a siso system with the coeficients fount in filename. Returns an integer Id, to identify the system during calls to other functions.

Id = \$LinSys_MisoInit(filename, input_array, [state_array]) : initialises a miso system with the coefficients fount in filename. input_array must be a real array that is big enough to hold all the input values. The input array is used during calculations. Returns an integer Id, to identify the system during calls to other functions.

Id = \$LinSys_MimoInit(filename, input_array, output_array, [state_array]) : initializes a mimo system with the coefficients fount in filename. input_array must be a real array that is big enough to hold all the input values.output_array must be a real array that is big enough to hold the output values. The input array is used during calculations. The output array contains the updated outputs after the calculations. Returns an integer Id, to identify the system during calls to other functions.

The optional state_array for these functions can be used to read back the value of the internal states of the models after calculation. This must ba a real array. The size must be at least the degree of the system.
5. Calculations

Output = \$LinSys_SisoCalc(Id, Input) : Calculates the siso system specified by Id for the current time. Input and Output are real.

Output = \$LinSys_MisoCalc(Id) : Calculates the miso system specified by Id for the current time. Before calling this function, the new input values must be entered in the input_array, specified during initialization. Output is real.

\$LinSys_MimoCalc(Id) : Calculates the mimo system specified by Id for the current time. Before calling this function, the new input values must be entered in the input_array, specified during initialization. The output is written into the output-array, specified during initialization.

When a state_array is specified during initialization, it is updated after the calculation. Writing to the state-array before calculations does not have any effect on the system. For changin the state, use \$LinSys_SetState function.
6. Special functions.

\$LinSys_GetState(Id, array) : copies the state values of the system specified by Id into the real array. The array must be big enough to hold all the state values of the system (so must contain at least 'order' values).

\$LinSys_SetState(Id, array) : copies the values from the real array into the internal state of the system specified by Id. The array must be big enough to hold all the state values of the system (so must contain at least 'order' values).

\$LinSys_CopyState(IdSrc, IdDest). Copies the internal state from the system with ID IdSrc to the system IdDest. Both systems must have the same degree.

Remark : for \$LinSys_SetState, and \$LinSys_CopyState, the internal time reference is set to the current time. So the next interpolation step will use the point where the state was copied for the calculation of delta t.

7. Examples : See the example directory.(samples/linsys_vpi/example)

8.VC7 Project/Source : See directory (samples/linsys_vpi)