Name
lowdisc_configure — Configure a field of the object and returns the modified object.
Calling Sequence
this = lowdisc_configure (this,key,value)
Parameters
- this:
the current object
- key:
a string. The name of the option to get. All options which can be set with lowdisc_configure can be get with lowdisc_cget.
- value:
the value associated with the key. Its type depends on the value of the key.
Description
This command allows to configure the state of the current object.
It requires to take the current object both as an input
and output argument.
The following keys are available.
- "-verbose" : a boolean, the verbose mode (default : %f).
- "-dimension" : a positive floating point integer,
the dimension of the space, i.e.
the size of the vector returned by the command lowdisc_next (default = 1).
- "-sequenceindex" : a positive floating point integer,
the starting index of the low discrepancy sequences.
When a sequence is created this setting is initialized to 0.
Whenever the randonumber_next method is called, the sequence index
is updated and incremented with 1. If this option is passed to the lowdisc_cget
method, it allows to know the number of vectors which have allready
been generated.
If this option is set, it allows to modify the behaviour of the low discrepancy
sequences, which take into account this index to produce the next element
in the sequence.
The -sequenceindex optin should therefore generally not be set,
except in specific situations
where the user has particular requirements on the low discrepancy
sequence to generate.
- "-skip" : a positive floating point integer,
the number of terms to skip at startup.
When the sequence is started up with the lowdisc_startup method,
the algorithm generates skip elements, which are immediately
discarded. This option allows to start the simulation at a later
point in the sequence.
For example, Fox recommends to skip the qs^4 - 2 first terms in the
Faure sequence, where qs is the prime number associated with the
sequence. This number can be retrieved with
qs = lowdisc_get ( lds , "-faureprime" ).
- "-leap" : a positive floating point integer,
the number of elements to ignore from element to element (default = 0).
Each time the lowdisc_next function is called, the immediate element
is retrieved. Then, in order to prepare for the next call,
there are leap elements which are generated and immediately
discarded. This option allows to generate alternative
sequences based on the same basic generator.
Some sequences can be configured in order to increase their maximum
dimension. These sequences accept the following "-primeslist" option.
- "-primeslist" : a row array of positive floating point integers,
at matrix of prime numbers used in the several low discrepancy sequences.
The expected matrix must have a 1xn shape, with n an integer greater than 2.
The default list is made of the 100 first prime numbers, from 2 to 541, which
enables the user to generate sequences up to 100 dimensions.
If a larger dimension problem is to process, that feature should enable users to
customize the list to meet the required dimension.
The user should be warned that the Halton sequence may produce poor convergence
rate if the dimension is larger than 15.
The sequences which are sensitive to this option are : "halton", "haltonf", "faure", "fauref",
"reversehalton", "reversehaltonf".
For the Fast Niederreiter sequence in arbitrary base, we can configure the
base.
- "-base" : a floating point number, greater than 2.
The base can be an odd or even integer.
The default value is 2.
It may be the smallest prime larger than the dimension as in the
Faure sequence, although it does not guarantee that this
leads to a lower discrepancy.
See the lowdisc_niederbase function for a suggestion of the optimal
base, depending on the dimension.
Some expertise is required to configure the skip and leap options.
The skip option can improve the Faure, Sobol and Niederreiter sequences.
The leap option can improve the Halton sequence, although
Kocis and Whiten also tried to leap the Faure and Sobol sequences.
This can lead to some trouble for non-experts.
For that purpose, we designed the following functions.
- lowdisc_haltonsuggest : provides settings for the Halton sequence,
- lowdisc_fauresuggest : provides settings for the Faure sequence,
- lowdisc_sobolsuggest : provides settings for the Sobol sequence,
- lowdisc_niedersuggest : provides settings for the Niederreiter sequence.
These functions have been designed to include suggestions by various authors to improve
the sequences.
In the situation where we have no knowledge of the settings to use, these
functions may be used. Still, these have not been included as defaults,
which authorizes a more aware choice of the parameters.
Some sequences are limited in the maximum number of dimensions,
because they use internally fixed tables of parameters (e.g. the Sobol
sequence).
Some other sequences can be extended with the "-primeslist" option.
The "-primeslist" option can be configure with a table of
primes computed with the lowdisc_primes100(), lowdisc_primes1000()
or lowdisc_primes10000() functions. The maximum dimension
which can be attained with these tables depends on the sequence.
See the specific settings of each sequence below for detail.
Examples
lds = lowdisc_new("faure");
lds = lowdisc_configure(lds,"-dimension",3);
method = lowdisc_cget(lds,"-method")
nbdim = lowdisc_cget(lds,"-dimension")
i = lowdisc_cget(lds,"-sequenceindex")
verbose = lowdisc_cget(lds,"-verbose")
lds
lds = lowdisc_destroy(lds);
Authors
Michael Baudin - 2008-2009 - INRIA |
Michael Baudin - 2010 - DIGITEO |