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