Simulate a multi-companion matrix

Simulate a multi-companion matrix with partially or fully specified spectral properties.

Usage

sim_mc(dim, mo, mo.col = dim, eigval, len.block, type.eigval = NULL,
       co, eigabs, eigsign, type = "real",
       value = "real", value.type = "", ...)

Arguments

dim: dimension of the matrix.
mo: multi-companion order.
mo.col: number of structural columns.
eigval: eigenvalues, one for each Jordan block.
len.block: lengths of the Jordan blocks corresponding to eigval.
type.eigval: types of the eigenvalues, a character vector
co: co parameters, see Details.
eigabs: moduli (absolute values) of eigenvalues, see Details.
eigsign: signs or complex arguments of eigenvalues, see Details.
type: passed down to generators (???)
value: what to return
value.type: type of the value (???)
...: further arguments to passed on to sim_chains and sim_numbers, see Details.

Details

sim_mc generates a multi-companion matrix of dimension dim x dim and multi-companion order mo. The matrix has the spectral properties specified by the arguments. Values that cannot be inferred from the arguments are simulated.

Arguments dim, mo, and mo.col define the structure of the matrix. The first two are compulsory but the last one, mo.col, is optional. If no other arguments are supplied sim_mc produces a matrix with all spectral parameters simulated.

The number of non-zero eigenvalues is at most mo.col. If mo.col < dim the multi-companion matrix has structural eigenvectors/chains corresponding to the zero eigenvalue(s), see the references. These chains are generated automatically.

Arguments type.eigval, eigabs, eigsign and eigval are vectors used to specify the types and the values of the eigenvalues. Any or all of them may be missing or NULL. Those present must have the same length.

It is not necessary to specify eigenvalues and eigenvectors corresponding to eigenvalues equal to zero, since the structural eigenchains needed when mo.col < dim are created automatically. In practice, the number of the non-zero eigenvalues is usually equal to mo.col. The net effect is that the arguments specifying the spectral structure of the matrix normally need to specify the spectral information about the non-zero eigval only.

Some or all of the eigenvalues may be specified partially or fully using arguments eigabs, eigsign, and eigval. Non-NA entries in eigval specify complete eigenvalues. Non-NA entries in eigabs specify absolute values of eigenvalues. Non-NA entries in eigsign specify signs of real eigenvalues or complex arguments of complex eigenvalues. Generally, if the entry for an eigenvalue in eigval is a number (not NA), then the corresponding entries in eigabs and eigsign will be NA. This is not enforced and a limited check for consistency is made in case of redundant information.

type.eigval is a character vector describing the types of the eigenvalues, where "r", "c", and "cp" stand for real, complex, and complex pair, respectively. It is best to have one entry only for each complex pair (specified by "cp"), rather than two "c" entries.

If type.eigval is NULL (default) and eigval is supplied, then type.eigval is inferred from the imaginary part of eigval ("r" or "cp"), if it is complex.

For compatibility with older versions of this function eigval may be a character vector in which case it is simply assigned to type.eigval.

If both, type.eigval and eigval, are missing a default allocation of the types of the eigenvalues is chosen.

TODO: complete the description below.

The remaining spectral parameters may be specified with the argument co with missing entries for the "free" entries. (!!! This is not complete, it may be better to have separate arguments for the absolute value and the angle, as for eigenvalues, and an option for normalisation of these coefficients. ???)

Generators other than the default ones may be specified in the ... argument. These are passed to sim_numbers and sim_chains. Again, for the "co" arguments the support is not finished.

Value

if value.type is the character string "matrix", the required multi-companion matrix. Otherwise, if

value.type=="list", a list containing also the spectral information (this list is the same as the one from

make_mcmatrix)).

References

Boshnakov GN (2002). “Multi-companion matrices.” Linear Algebra Appl., 354, 53--83. ISSN 0024-3795, doi:10.1016/S0024-3795(01)00475-X .

Boshnakov GN, Iqelan BM (2009). “Generation of time series models with given spectral properties.” J. Time Series Anal., 30(3), 349--368. ISSN 0143-9782, doi:10.1111/j.1467-9892.2009.00617.x .

Author

Georgi N. Boshnakov

Note

A canonical form is needed, especially when there are repeated eigenvalues whose eigenvectors may be chosen to be orthogonal, at least. (nyakade v zapiskite mi tryabva da ima kanonichna forma!)

Examples

m0 <- sim_mc(3,2)   # simulate 3x3 2-companion matrix
abs(m0$eigval)      # eigval random, so their abs values
#> [1] 0.5768442 0.8157983 0.8157983

# now fix moduli of eigenvalues, and
# ask for one real ev and one complex pair of ev's
m1 <- sim_mc(3,2,eigabs=c(0.25,0.5), type.eigval=c("r","cp"))
m1$eigval
#> [1] -0.2500000+0.0000000i -0.4018284-0.2975466i -0.4018284+0.2975466i
abs(m1$eigval)
#> [1] 0.25 0.50 0.50

# same as above, since type.eigval happens to be the default
# dim is odd, by default first ev is real, rest are complex pairs
m1a <- sim_mc(3,2,eigabs=c(0.25,0.5))
m1a$eigval
#> [1] -0.2500000+0.0000000i -0.4964316-0.0596294i -0.4964316+0.0596294i
abs(m1a$eigval)
#> [1] 0.25 0.50 0.50

# simulate 6x6 4-companion matrix
# with ev's at the seasonal frequencies (1.57 3.141593 -1.57)
# and random moduli. 3 complex pairs of ev's
m2 <- sim_mc(6,4, eigsign = pi*c(1/2,1,-1/2) )
Arg(m2$eigval)
#> [1]  1.570796  3.141593 -1.570796 -1.570796 -3.141593  1.570796