sim_mc {mcompanion}

Simulate a multi-companion matrix

Description

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)).

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!)

Author(s)

Georgi N. Boshnakov

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.

See Also

gbutils::sim_numbers and sim_chains for arguments that control the distributions of the random numbers.

make_mcmatrix creates the matrix.

Examples

m0 <- sim_mc(3,2)   # simulate 3x3 2-companion matrix
abs(m0$eigval)      # eigval random, so their abs values

# 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
abs(m1$eigval)

# 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
abs(m1a$eigval)

# 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)