rank_1_lattice

Uses rank-1 lattice points to sample variables

Specification

• Alias: None

• Arguments: None

• Default: No rank-1 lattice sampling

Child Keywords:

Required/Optional	Description of Group	Dakota Keyword	Dakota Keyword Description
Optional		no_random_shift	Do not shift this rank-1 lattice
Optional		m_max	log2 of the maximum number of points in the lattice
Optional		generating_vector	Specify the generating vector of this rank-1 lattice rule
Optional		ordering	Ordering of the points of this rank-1 lattice

Description

The rank_1_lattice keyword invokes rank-1 lattice sampling as the means of drawing samples of uncertain variables according to their probability distributions [NC06].

Rank-1 lattices were introduced by Korobov [Kor59] and Hlawka [Hla62], as the method of good lattice points. An \(N\)-point rank-1 lattice rule in \(d\) dimensions generates points according to

\[\boldsymbol{t}^{(i)} = \left\{ \frac{i \boldsymbol{z}}{N} \right\} = \frac{i \boldsymbol{z} \;\text{mod}\; N}{N}\]

where \(\{\;\cdot\;\}\) denotes the fractional part, i.e., \(\{x\} = x - \lceil x \rceil\), and where \(\boldsymbol{z} = (z_1, z_2, \ldots, z_d)\) is a \(d\)-dimensional vector with integers, called the generating vector.

The performance of the rank-1 lattice points depends on the choice of generating vector. Dakota provides two predefined generating vectors:

• cools_kuo_nuyens (default): generates up to 2²⁰ points in up to 250 dimensions [CKN06]

• kuo: generates up to 2²⁰ points in up to 3600 dimensions [Kuoa]

If this is not sufficient, you can provide a custom generating vector either as an inline argument, or using an external file. Custom generating vectors can be found online [Kuoa], or they can be generated using the fast component-by-component construction from [Nuy]. When a custom generating vector is provided, the user must specify the \(\log_2\) of the maximum number of points in the lattice using the keyword m_max.

By default, the lattice points will be shifted using a random shift vector. This means that the points will be generated as

\[\boldsymbol{t}^{(i)} = \left\{ \frac{i \boldsymbol{z}}{N} + \Delta \right\}\]

where \(\Delta\) is a vector with standard uniform random points. If this is not the desired behavior, specify the keyword no_random_shift (warning: this means that the first untransformed point in the sequence will be \(\boldsymbol{t}^{(0)} = (0, 0, \ldots, 0)\) – this may or may not be the desired behavior [Owe20].)

The default behavior is to return points using radical inverse ordering, i.e., the points will be generated according to

\[\boldsymbol{t}^{(i)} = \left\{ \phi_b(i) \boldsymbol{z} \right\}\]

where \(\phi_b(i)\) denotes the so-called radical inverse function in base \(b\) (usually, and also in Dakota, \(b = 2\)). This function transforms a number \(i = (\ldots i_2i_1)_b\) in its base-\(b\) representation to \(\phi_b(i) = (0.i_1i_2\ldots)_b\). Note that the radical inverse function agrees with the original formulation when \(N = b^m\) for any \(m \geq 0\). The advantage of the radical inverse ordering is that one can generate a good point set with an arbitrary number of points \(N\). Using the natural order, a good point set requires a number of points that is a power of 2. Semantically, the radical inverse ordering turns the lattice rule into a lattice sequence. Use the keyword ordering to choose the ordering of the point set.

Examples

environment
  tabular_data
    tabular_data_file = 'samples.dat'
    freeform

method
  sampling
    samples 32
    sample_type
      low_discrepancy
        rank_1_lattice

variables
  uniform_uncertain = 2
    lower_bounds 0.0 0.0
    upper_bounds 1.0 1.0

interface
  analysis_drivers = 'genz'
  analysis_components = 'cp1'
  direct

responses
  response_functions = 1
  no_gradients
  no_hessians