digital_net

Uses digital net points to sample variables

Specification

• Alias: sobol_sequence

• Arguments: None

• Default: No digital net sampling

Child Keywords:

Required/Optional	Description of Group	Dakota Keyword	Dakota Keyword Description
Optional		no_digital_shift	Do not shift this digital net
Optional		no_scrambling	Do not scramble this digital net
Optional		integer_format	Specify format of integers in the generating matrices
Optional		m_max	log2 of the maximum number of points in the digital net
Optional		t_max	Bit depth of the generating matrices
Optional		t_scramble	Number of rows in the affine scramble matrices
Optional		generating_matrices	Specify the generating matrices of this digital net
Optional		ordering	Ordering of the points of this digital net

Description

The digital_net keyword invokes digital net sampling as the means of drawing samples of uncertain variables according to their probability distributions [DP10]. The Sobol sequence is a particularly famous example of a digital net [Sobol67]. When this keyword is provided, it must be accompanied by the keyword low_discrepancy.

Digital nets and sequences were introduced by Niederreiter, building upon earlier work by Sobol and Faure [Nie87]. In the digital construction scheme, a sequence in \(d\) dimensions generates points \(\boldsymbol{t}^{(i)} = (t_{i, 0}, t_{i, 1}, \ldots, t_{i, d})\), where the \(j\)th component \(t_{i, j}\) is constructed as follows:

1. Write \(i\) in its base-\(b\) representation, i.e.,

\[i = (\ldots i_3 i_2 i_1)_b = i_1 + i_2 b + i_3 b^2 + \ldots\]

2. Compute the matrix-vector product

\[\begin{split}\begin{pmatrix} y_1 \\ y_2 \\ y_3 \\ \vdots \end{pmatrix} = C_j \begin{pmatrix} i_1 \\ i_2 \\ i_3 \\ \vdots \end{pmatrix}\end{split}\]

where all additions and multiplications are performed in base \(b\).

3. Set the \(j\)th component of the \(i\)th points to

\[t^{(i)}_j = \frac{y_1}{b} + \frac{y_2}{b^2} + \frac{y_3}{b^3} + \ldots = (0.y_1y_2y_3\ldots)_b\]

The matrices \(C_j\), \(j=1, 2, \ldots, d\) are known as generating matrices.

The performance of the digital net points depends on the choice of the generating matrices. Dakota provides two predefined sets of generating matrices:

• joe_kuo (default): generates up to 2³² points in up to 250 dimensions [JK08]

• sobol_order_2: generates up to 2³² points in up to 1024 dimensions [CHMS20]

If this is not sufficient, you can provide a custom set of generating matrices either as an inline argument, or using an external file. Custom generating matrices can be found online at [Kuob], [Nuy]. In this case, the user must specify the log2 of the maximum number of points in the sequence using the keyword m_max, as well as the bit depth of the generating matrices t_max.

By default, the digital points will be shifted using a digital shift vector. If \(\Delta\) is a vector of standard uniform random numbers, then we compute \(\boldsymbol{t}^{(i)} \otimes \Delta\), where \(\otimes\) is the element-wise \(b\)-ary addition operator, see [DP10]. If this is not the desired behavior, specify the keyword no_digital_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].)

Ideally, the digital net should preserve the structure of the points after randomization. This can be achieved by scrambling the digital net. Scrambling can also improve the rate of convergence of a method that uses these scrambled points to compute the mean of the model response. Owen’s scrambling [Owe98] is the most well-known scrambling technique. A particular variant is linear matrix scrambling, which is implemented in Dakota [Matouvsek98]. To disable scrambling of the points, use the keyword no_scrambling.

The default behavior is to return points using Gray code ordering such that the digital net becomes a digital sequence with good performance for an arbitrary number of points \(N\). The Gray code ordering has an additional advantage in that there exists an iterative procedure to generate the successive points of the sequence, see gray_code. Use the keyword ordering to choose the ordering of the point set.

Notes

A computer implementation of a Sobol sequence generator in Fortran 77 was given by Bratley and Fox [BF88] as Algorithm 659. This implementation allowed points of up to 40 dimensions. It was extended by Joe and Kuo to allow up to 1111 dimensions in [JK03] and up to 21201 dimensions in [JK08]. In the Dakota implementation of the algorithm outlined above, we use the iterative construction from Antonov and Saleev [AS79].

Examples

environment
  tabular_data
    tabular_data_file = 'samples.dat'
    freeform

method
  sampling
    samples 128
    sample_type
      low_discrepancy
        digital_net # this is the default option

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