RFoptions sets and returns control arguments for the analysis
and the simulation of random fields
RFoptions(..., no.class=FALSE, install.control=NULL)arguments in tag = value form, or a list of tagged
values. See ‘Details’ for options in package
RandomFieldsUtils.
logical. If TRUE the list is returned without
class specification.
list. See Details, Part 2
NULL if any argument is given, and the full list of
arguments, otherwise.
The subsections below comment on
1. basic: Basic options
2. install.control
3. installNrun: Options for installation and running
4. solve: Options for solving linear systems
5. Reserved words
1. Basic options
asListlogical. Lists of arguments are treated slightly
different from non-lists. If asList=FALSE they are treated the
same way as non-lists. This options being set to FALSE after
calling RFoptions it should be set as first element of a list.
Default: TRUE
coresNumber of cores for multicore algorithms; currently only used for the Cholesky decomposition.
Default : 1 if the package has been compiled with
standard flags of CRAN and
0.75 * cores() + 0.25 * cpus() else.
Note that cores has not effect if set locally in this
package or in package miraculix.
cPrintlevelcPrintlevel is automatically set to printlevel
when printlevel is changed.
Standard users will never use a value higher than 3.
0 : no messages 1 : messages and warnings when the user's input looks odd 2 : messages (and internal errors) documenting the choice of the simulation method 3 : further user relevant informations 4 : information on recursive function calls 5 : function flow information of central functions 6 : errors that are internally treated 7 : details on building up the covariance structure 8 : details on taking the square root of the covariance matrix 9 : details on intermediate calculations 10 : further details on intermediate calculations
Note that printlevel works
on the R level whereas cPrintlevel works on the C level.
cPrintlevel should be changed only globally.
Default: 1
logical.
If TRUE then always the most time efficient code is used.
Default: TRUE.
It is strongly recommended to retain this value.
helpinfological. If TRUE then
additional information is printed for more efficient programming
in R.
Default: TRUE
printlevelIf printlevel\(\le0\)
there is not any output on the screen. The
higher the number the more tracing information is given.
Standard users will never use a value higher than 3.
0 : no messages 1 : important (error) messages and warnings 2 : less important messages 3 : details, but still for the user 4 : recursive call tracing 5 : function flow information of large functions 6 : errors that are internally treated 7 : details on intermediate calculations 8 : further details on intermediate calculations
Default: 1
seedinteger (currently only used by the package
RandomFields).
If NULL or NA
set.seed
is not called.
Otherwise,
set.seed(seed)
is set
before any simulations are performed.
If the argument is set locally, i.e., within a function,
it has the usual local effect. If it is set globally, i.e. by
RFoptions the seed is fixed
for all subsequent calls.
If the number of simulations n is greater than one
and if RFoptions(seed=seed) is set, the \(i\)th
simulation is started with the seed ‘seed\(+i-1\)’.
skipcheckslogical.
If TRUE, several checks whether the given parameter values
and the dimension are within the allowed range is skipped.
Do not change the value of this variable except you really
know what you do.
Default: FALSE
verboselogical. If FALSE it identical to
printlevel = 1 else to printlevel = 2.
bigendianlogical. Read only.
2. install.control: Details on argument install.control
install.control may contain any argument of
install.packages except type.
This options is currently tailored for MS and Linux on Intel
machines, only.
The argument configure.args
may not contain 'CXX_FLAGS'
which should be passed as an extra argument with the list.
Note that if this argument is given (even with value NULL),
an immediate installation takes place. In case the user tries to
force to install 0 packages, an overview over the packages is given.
If the user is asked whether re-installation shall take place,
user can pass arguments to install.packages, e.g.,
"quiet=FALSE".
If install.control is given, no further
argument may be passed to RFoptions.
Additional components of install.control and special
behaviours are:
paththe path to the locally saved tar balls
verbose, quietThey affect also the behaviour of RFoptions.
forceTRUEreinstallation of all attached libraries based on and including
RandomFieldsUtils. I.e.,
RFoptions(install.control=list(force=TRUE)) is the
strongest form of forcing reinstallation.
FALSEIn case some packages have to be re-installed the user will be asked.
reinstallation of the attached libraries based on and including RandomFieldsUtils that have not been tried yet in the current session.
pkgs=NULLbrief overview over the installed packages based on
RandomFieldsUtils
CROSSlogical or character. CROSS is passed to configure.ac.
"noflag"No extra compiler flag is set with respect to SIMD. This is the default.
TRUEeach file is compiled with its specific SIMD/AVX compiler flags; this guarantees the compatiblity on a plattform with different sets of kernels. No SIND/AVX flag should be given by the user. Cross-compilation supported; no check is performed whether the code would run on the compiling CPU.
"nosimd"It is assumed that no SIMD is available and the flag "-no-sse2" is set (if possible).
"sse2"Same behaviour as TRUE, but all
CPUs have at least "sse2" available.
"sse3", "ssse3", "sse41",
"avx", "avx2"
Alternatives to "sse2".
Giving the highest guaranteed SIMD recognition leads to
the most efficient code.
FALSEeach file is compiled with all SIMD/AVX flags recognized by both the CPU and the compiler (no cross-compilation); users may add their own SIMD/AVX flags. This might lead to faster code, but which is not downwards compatible.
NASame as FALSE except
that the flag -mno-sse2
is set when no SIMD is needed or used.
"avx" interactively if
install="ask".CC_FLAGScharacter. Flags passed to configure.ac.
SIMD_FLAGScharacter. A subset of "sse2",
"sse3", "ssse3", "sse41", "avx",
"avx2", "arch=xxx", etc.
which will be tried instead of default flags.
SIMD_FLAGS is passed to configure.ac.
LOCAL_ONLYlogical. If TRUE, the web is not
searched for the latest version of the package.
MEM_IS_ALIGNEDlogical. If TRUE, then the memory
is assumed to be aligned. If FALSE then the SIMD
load commands _mm_*load_*
are replaced by _mm_*loadu_*.
If given, then force is set to TRUE.
USE_GPUlogical. Force or hinder the compilation for the GPU
3. installNrun: Options for installing and for
determining basic behaviour
installcharacter. Only used by linux systems and
alike including macOS
The default by CRAN is that SIMD/AVX cannot be used at full extend.
install determines what the action if the compiled
version does not use the full CPU capacities. Since the use of GPU
is heavily hardware dependent, its auto-recompilation is only performed
in tow line of an AVX re-compilation.
The users usually use
"no"no re-installation
"ask"asks whether the library should be reinstalled, using the full capacity of the CPU according to the package.
"install"performs the auto-recompilation without asking.
Note that only the command
RFoptions(install.control=list(force=TRUE))
forces re-compilation of the currently loaded packages that are based on
RandomFieldsUtils.
install.control
for overwriting this behaviour.Default: at starting point it is "ask" or "no",
but the value may change during the session.
installPackageslogical. Read only.
Indicates whether packages are left to be re-installed.
RFoptions(install="no") sets it to FALSE.
RFoptions(install="no", install="ask") sets it to TRUE.
kahanCorrectionobsolete.
logical. If TRUE, the Kahan summation algorithm is used for
calculating scalar products.
Default: false
la_modedetermines
"auto"If a graphic card is recognized, LA_GPU is used.
In all other cases the default is primarily LA_R.
Only on linux systems, the package peforms a simple speed test and
takes LA_INTERN if it is faster than LA_R; the time,
hence the choice, depends also on the number of cores used.
"intern"mostly own algorithms, often based on SIMD/AVX. This option is of interest only if no advanced BLAS/LAPACK has been compiled into R
"R"BLAS/LAPACK implementation used by R
"GPU"This option is available when the package has been compiled with nvcc.
"query"Request on currently used set-up
Default: LA_AUTO
MEM_IS_ALIGNED in install.control.warn_parallelLogical.
RandomFieldsUtils and
packages using it, such as RandomFields and miraculix,
should now be prepared for parallelization using package
parallel, for instance. Internal OMP parallelization
of RandomFieldsUtils is done, but only at a view points
of the subsequent packages.
As a few parts cannot be in parallel technically
or from a logical point of view, a hint or a
warning is given, if such a point is not accessed adequately.
These messages can be turned off by warn_parallel = FALSE.
Default: TRUE.
warn_unknown_optioninteger.
0,1,-1Unknown options are all ignored. If the value is positive, a hint is delivered whenever an unknown option is ignored.
-2,2Unknown options that start with a capital letter are ignored.
All others lead to an error. (Note that all RFoptions
start with a minor letter.)
If the value is positive,
a hint is delivered whenever an unknown option is ignored.
3,-3Unknown options that consists of a single capital letter are ignored.
All others lead to an error. (Note that all RFoptions
start with a minor letter.)
If the value is positive,
a hint is delivered whenever an unknown option is ignored.
4(and other values) Any unknown option leads to an error.
Default for RandomFieldsUtils: 3
Default for RandomFields: 1
4. solve: Options for solving linear systems
det_as_logeigen2zeroWhen the svd or eigen decomposition is calculated,
all values with modulus less than or equal to eigen2zero
are set to zero.
Default: 1e-12
max_cholinteger. Maximum number of rows of a matrix in a Cholesky decomposition
Default: \(16384\)
max_svdinteger. Maximum number of rows of a matrix in a svd decomposition
Default: \(10000\)
pivot_partialdetlogical. If TRUE then in case
of low-rank matrices the determinant is calculated only in the part
with positive eigenvalues
pivotType of pivoting for the Cholesky decomposition. Possible values are
"no"No pivoting.
"auto"If the matrix has a size greater than
3x3 and Choleskey fails without pivoting, privoting
is done. For matrices of size less than 4x4, no pivoting and
no checks are performed. See also PIVOT_DO
"do"Do always pivoting. NOTE: privoted Cholesky decomposition yields only very approximately an upper triangular matrix L, but still L^t L = M holds true.
"idx"uses the same pivoting as in the previous pivoted decomposition. This option becomes relevant only when simulations with different parameters or different models shall be performed with the same seed so that also the pivoting must be coupled.
Default: PIVOT_NONE
pivot_actual_sizeinteger.
Genuine dimension of the linear mapping given by a matrix in cholx.
This is a very rarely used option when pivoting with
pivot=PIVOT_IDX.
pivot_checklogical. Only used in pivoted Cholesky
decomposition.
If TRUE and a numerically zero diagonal element is detected,
it is checked whether the offdiagonal elements are numerically zero
as well.
(See also pivot_max_deviation and
pivot_max_reldeviation.)
If NA then only a warning is given.
Default: TRUE
pivot_idxvector of integer.
Sequence of pivoting indices in pivoted Cholesky decomposition.
Note that
pivot_idx[1] gives the number of indices that will be
used. The vector must have at least the length
pivot_idx[1] + 1.
Default: NULL
pivot_relerrorpositive number. Tolerance for (numerically) negative eigenvalues and for (numerically) overdetermined systems appearing in the pivoted Cholesky decomposition.
Default: 1e-11
pivot_max_deviationpositive number.
Together with pivot_max_reldeviation it determines
when the rest of the matrix (eigenvalues) in the pivoted
Cholesky decomposition are considered as zero.
Default: 1e-10
pseudoinverselogical. In case of a singular matrix \(M\),
shall the pseudo inverse be returned for solvex(M)?
Default: FALSE
pivot_max_reldeviationpositive number.
Together with pivot_max_deviation it determines
when the rest of the matrix (eigenvalues) in the pivoted
Cholesky decomposition are considered as zero.
Default: 1e-10
solve_methodvector of at most 3 integers that gives the sequence of methods
in order to inverse a matrix or to calculate its square root:
"cholesky", "svd", "lu",
"eigen" "sparse",
"method undefined". In the latter case, the algorithm decides
which method might suit best.
Note that if use_spam is not false the algorithm
checks whether a sparse matrix algorithm should be used and which is
then tried first.
Default: "method undefined".
spam_factorinteger. See argument spam_sample_n.
Default: 4294967
spam_min_ninteger vector of size 2. The minimal size for a matrix to apply a sparse matrix algorithms automatically. The second value is used in case the GPU is activated.
Default: c(400, 4000)
spam_min_p (spam_min_p)a numbers in \((0,1)\) giving the proportion of zero above which an sparse matrix algorithm is used. The second value is used in case the GPU is activated.
Default: 0.8 (0.9)
spam_pivotinteger. Pivoting algorithm for sparse matrices:
No pivoting
spam for details.Default: PIVOTSPARSE_MMD
spam_sample_n (spam_sample_n_GPU)Whether a matrix is sparse or not is tested by a
‘random’ sample of size spam_sample_n;
The selection of the sample is iteratively
obtained by multiplying the index by spam_factor
modulo the size of the matrix.
Default: 500 (10000).
spam_tollargest absolute value being considered as zero.
Default: DBL_EPSILON
svdtolInternal.
When the svd decomposition is used for calculating the square root of
a matrix then the absolute componentwise difference between
this matrix and the square of the square root must be less
than svdtol. No check is performed if
svdtol is not positive.
Default: 0
use_spamShould the package spam (sparse matrices)
be used for matrix calculations?
If TRUE spam is always used. If FALSE,
it is never used. If NA its use is determined by
the size and the sparsity of the matrix.
Default: NA.
5. Reserved Words
list_list_ usually equals the output of RFoptions().
This argument is used to reset the RFoptions.
Some of the options behave differently if passed through
list_. E.g. a warning counter is not reset.
The argument list_ cannot be combined with any other arguments.
getoptions_string vector of prefixes that indicate
classes of options. In this package they
can be "basic" and "solve". (E.g. package
RandomFields has many more classes of options.)
The given classes of options are then
returned by RFoptions(). Note that the values are the
previous values.
getoptions_ must always be the very first argument.
saveoptions_string vector of prefixes. Same as for
getoptions_, except that important classes are always
returned and thus should not be given. Hence saveoptions_
is often a convenient short cut for getoptions_.
The class always included in this package is "basic", in
package RandomFields these are the two classes
"basic" and "general".
saveoptions_ must always be the very first argument. In
particular, it may not given at the same time with getoptions_.
local_logical. This options is allowed only when advanced packages are used, see RandomFields.
warnUnknown_integer. Same as option
warn_unknown_option, except that its value overwrites
the value of warn_unknown_option in the current command
RFoptions. This options must be placed between CODE
and getoptions_, if the latter are used.
# NOT RUN {
<!-- % library(RandomFieldsUtils) -->
# }
# NOT RUN {
n <- 10
M <- matrix(1, ncol=n, nrow=n)
# }
# NOT RUN {
try(chol(M)) ## error, as M is not strictly positive definite
try(cholx(M)) ## also fails
# }
# NOT RUN {
# }
# NOT RUN {
<!-- %cholx(M) ## works -->
# }
# NOT RUN {
RFoptions(la_mode=LA_INTERN, pivot=PIVOT_AUTO)
cholx(M) ## works
RFoptions(la_mode=LA_R)
RFoptions(solve_method="svd", pseudoinverse=TRUE)
solvex(M)
RFoptions(solve_method="method undefined", pseudoinverse=FALSE)
# }
Run the code above in your browser using DataLab