Create Test Rational Matrix in Statespace Form — test

This simple tool may be used to create a random, \((m,n)\)-dimensional, rational matrix in statespace form with statespace dimension \(s\).

Usage

test_stsp(
  dim = c(1, 1),
  s = NULL,
  nu = NULL,
  D = NULL,
  digits = NULL,
  bpoles = NULL,
  bzeroes = NULL,
  n.trials = 100
)

Arguments

dim: integer vector c(m,n).
s: state dimension (or NULL).
nu: vector with the Kronecker indices (or NULL). Either the statespace dimension s or the Kronecker indices nu must be non NULL. If both parameters are given, then the parameter s is ignored.
D: \((m,n)\) dimensional matrix (or NULL). See the details below.
digits: integer, if non NULL then the randomly generated numbers are rounded to "digits" number of decimal places.
bpoles: lower bound for the moduli of the poles of the rational matrix (or NULL).
bzeroes: lower bound for the moduli of the zeroes of the rational matrix (or NULL). This parameter is ignored for non-square matrices (m != n).
n.trials: maximum number of trials.

Value

stsp object, which represents the generated rational matrix

\(x(z)\) in statespace form.

Details

If the Kronecker indices (parameter nu) are given, then a statespace model in echelon canonical form is generated. This means that some of the entries of the \(A,B,C\) matrices are fixed to be one or zero and the others are considerd as "free". See also Kronecker-Indices. The entries of the \(A, B, C\) matrices, which are not a priori fixed are randomly generated.

If only the state dimension \(s\) (parameter s) is given, then all entries of the \(A, B, C\) matrices are considered as "free".

The \(D\) matrix defaults to a \((m,n)\)-dimensional diagonal matrix with ones on the diagonal (diag(x=1, nrow = m, ncol = n)). However, one may also pass an arbitray (compatible) \(D\) matrix to the procedure. This matrix may contain NA's, which then are replaced by random numbers.

The user may prescribe lower bounds for the moduli of the poles and the zeroes of the rational matrix. In this case the procedure simply generates (up to n.trials) random matrices until a matrix is found which satisfies the constraints. The standard deviation of the normal distribution, which is used to generate the random entries, is decreased in each step. Of course this is a very crude method and it may fail or need a very large number of randomly generated matrices.

Note also, that the generated model may be non-minimal.

Examples

## random (2 x 2) statespace realization with state dimension s = 3
## no poles and zeroes within the unit circle
x = test_stsp(dim = c(2,2), s = 3, digits = 2, bpoles = 1, bzeroes = 1)
x
#> statespace realization [2,2] with s = 3 states
#>       s[1]  s[2]  s[3]  u[1]  u[2]
#> s[1]  0.12 -0.23 -0.57  0.47 -0.70
#> s[2]  0.02 -0.22 -0.51 -0.68 -0.41
#> s[3] -0.02  0.51  0.36  1.04 -0.54
#> x[1]  0.38 -0.46  0.21  1.00  0.00
#> x[2] -1.13 -0.88  1.86  0.00  1.00
min(abs(poles(x))) > 1
#> [1] TRUE
min(abs(zeroes(x))) > 1
#> [1] TRUE
pseries2nu(pseries(x, lag.max = 5)) # Kronecker indices
#> [1] 2 1

## random (3 x 2) statespace realization in echelon canonical form
## D is lower triangular (with ones on the diagonal)
## no poles within the unit circle
x = test_stsp(dim = c(3, 2), nu = c(2,3,0), D = matrix(c(1,NA,NA,0,1,NA), nrow = 3, ncol = 2), 
              digits = 2, bpoles = 1)

x
#> statespace realization [3,2] with s = 5 states
#>       s[1]  s[2]  s[3]  s[4]  s[5]  u[1]  u[2]
#> s[1]  0.00  0.00  1.00  0.00  0.00  0.22 -0.53
#> s[2]  0.00  0.00  0.00  1.00  0.00 -0.93  0.05
#> s[3]  0.43 -0.40 -0.48 -0.21  0.00  0.65  0.07
#> s[4]  0.00  0.00  0.00  0.00  1.00  0.19  1.11
#> s[5] -0.07  0.43  0.12  0.66 -0.07  0.12  0.53
#> x[1]  1.00  0.00  0.00  0.00  0.00  1.00  0.00
#> x[2]  0.00  1.00  0.00  0.00  0.00  0.24  1.00
#> x[3]  0.11 -0.44  0.00  0.00  0.00  0.20 -0.27
min(abs(poles(x))) > 1
#> [1] TRUE
pseries2nu(pseries(x, lag.max = 10)) # check Kronecker indices
#> [1] 2 3 0