sim_numbers: Simulation based on polar form specifications In gbutils: Simulation of Real and Complex Numbers and Small Programming Utilities

Description

Simulate real and complex numbers from polar form specifications. The numbers may be partially or fully specified. The distributions of absolute values and arguments/signs are specified independently.

Usage

 ```1 2 3``` ```sim_numbers(type = rep(as.character(NA), length(abs)), abs = rep(as.numeric(NA), length(type)), sign = rep(as.numeric(NA), length(type)), values = NULL, ...) ```

Arguments

 `type` character vector specifying the types of the eigenvalues, see Details. `abs` vector of absolute values (moduli). `sign` vector of signs (for reals) and arguments (for complex numbers), see Details for interpretation. `values` values, see details. `...` additional arguments to be passed to `sim_real` and `sim_complex`.

Details

`sim_numbers` simulates a vector of real and complex numbers with given distributions of their polar parts. It is possible also to fix some of the numbers or one of their polar parts. The length of the simulated vector is inferred from the length of `type` or `abs`, so one of them must be provided. `sim_numbers` as a flexible front-end for `sim_real` and `sim_complex`.

`sim_numbers` generates a vector of values with types specified by argument `type` and/or inferred from argument `values`. The recommended way to use `sim_numbers` is to provide argument `type`.

`type[i]` specifies the type of the i-th element of the result: real (`type[i]=="r"`), complex (`type[i]=="c"`) or representing a complex conjugate pair (`type[i]=="cp"`). If `values` is provided, the imaginary parts of its non-NA elements are used to fill `NA` elements of `type` ("r" if zero, "cp" otherwise).

Some (or even all) values may be fixed or partially fixed with the help of arguments `abs`, `sign` and `values`. A non-missing value of `values[i]` fixes the i-th element of the result to that value. Simlarly `abs[i]` fixes the modulus and `sign[i]` fixes the sign/argument of the i-th element. If `values[i]` is not `NA`, then it takes precedence and `abs[i]` and `sign[i]` are ignored.

For real numbers `sign` is the sign with possible values 1 (positive) or -1 (negative). For complex numbers, `sign` is the argument and is in the interval (-pi,pi).

If `values` is supplied, then `NA` entries in `type` are replaced by "r" or "cp" depending on whether or not the imaginary parts of the corresponding entries in `values` are equal to zero. A check is done for consistency when both `type[i]` and `values[i]` are non-missing. Generally, `values` is meant to be used for values that are fixed and available directly in Cartesian form, to avoid having to fill the corresponding entries of `abs` and `sign`.

`NA` entries of `abs` and `sign` are filled with simulated values, the remaining entries are considered fixed and left unchanged. The default generator is uniform (0,1) for `abs`, uniform (-pi,pi) for the argument of complex values, and 1 or -1 with p=1/2 for the sign of real values.

To specify a different generator for the moduli and absolute values, use argument `absgen`, giving it a function or the name of a function. The arguments for this function can be specified by `absarg` (as a list). Similarly, the generator for arguments of complex numbers can be specified by `arggen` and `argarg`. Finally, the probability for the real numbers to be positive is given by `signprob`. These arguments are not in the signature of the function since they are passed on directly (via `"..."`) to the underlying `sim_complex` and `sim_real`, see their documentation and the examples below for further details.

Value

a list with components

 `values` vector of values; it is of type `numeric` if all values are real and `complex` otherwise. `type` a character vector of the types as above

Note

Values of type "cp" (complex pairs) are represented by one element, the complex conjugate elements are NOT generated. (todo: maybe add an argument to control this)

The convention for the sign of a real eigenvalue is 1 and -1, not 0 and pi.

The checks for consistency between `type` and `values` are not complete and only straightforward use is recommended.

The current defaults for the arguments, see the signature above, require that at least one of `type` and `abs` is not missing.

Author(s)

Georgi N. Boshnakov

`sim_real` , `sim_complex`
 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44``` ```## one real number and one complex conjugated pair ## (maybe to specify a cubic polynomial through its roots) sim_numbers(type = c("r", "cp")) ## here the real value is fixed to have modulus 1, leaving the sign unspecified sim_numbers(type = c("r", "cp"), abs = c(1, NA)) ## now the real value is fixed to 1, ## the complex pair has argument +-pi/2, and free modulus: sim_numbers(type = c("r", "cp"), abs = c(1, NA), sign = c(0, pi/2)) ## using argument 'values' to fix some values; ## here the the third value is fixed: sim_numbers(type = c("r", "cp", "r"), values = c(NA,NA,3)) # type[3] = "r" sim_numbers(type = c("r", "cp", "cp"), values = c(NA,NA,3i)) # type[3] = "cp" ## type[3] can be left NA since it can be inferred from values[3]: sim_numbers(type = c("r", "cp", NA), values = c(NA,NA,3)) # type[3] = "r" sim_numbers(type = c("r", "cp", NA), values = c(NA,NA,3i)) # type[3] = "cp" ## it is an error to have a mismatch between args `type' and value: ## Not run: sim_numbers(type = c("r", "cp", "cp"), values = c(NA,NA,3)) sim_numbers(type = c("r", "cp", "r"), values = c(NA,NA,3i)) ## End(Not run) ## simulate 10 reals with the default generators sim_numbers(rep("r", 10)) ## simulate modulus from Rayleigh distribution ## rR <- function(n, sigma = 1) sigma * sqrt(-2*log(runif(n))) sim_numbers(type = c("cp", "cp"), absgen = rR, absarg = list()) # test the the components are N(0,1) ## (not run to save time for CRAN check) ## \dontrun{ ## v <- sim_numbers(type = rep("cp", 10000), absgen = "rR", ## absarg = list(sigma = 1)) ## ks.test(Re(v\$values), "pnorm") ## ks.test(Im(v\$values), "pnorm") ## } ```