.. _method-sampling-sample_type-low_discrepancy-digital_net:

"""""""""""
digital_net
"""""""""""


Uses digital net points to sample variables



.. toctree::
   :hidden:
   :maxdepth: 1

   method-sampling-sample_type-low_discrepancy-digital_net-no_digital_shift
   method-sampling-sample_type-low_discrepancy-digital_net-no_scrambling
   method-sampling-sample_type-low_discrepancy-digital_net-integer_format
   method-sampling-sample_type-low_discrepancy-digital_net-m_max
   method-sampling-sample_type-low_discrepancy-digital_net-t_max
   method-sampling-sample_type-low_discrepancy-digital_net-t_scramble
   method-sampling-sample_type-low_discrepancy-digital_net-generating_matrices
   method-sampling-sample_type-low_discrepancy-digital_net-ordering


**Specification**

- *Alias:* sobol_sequence 

- *Arguments:* None

- *Default:* No digital net sampling


**Child Keywords:**

+-------------------------+--------------------+-------------------------+-----------------------------------------------+
| Required/Optional       | Description of     | Dakota Keyword          | Dakota Keyword Description                    |
|                         | Group              |                         |                                               |
+=========================+====================+=========================+===============================================+
| 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    |
+----------------------------------------------+-------------------------+-----------------------------------------------+

.. __: method-sampling-sample_type-low_discrepancy-digital_net-no_digital_shift.html
__ method-sampling-sample_type-low_discrepancy-digital_net-no_scrambling.html
__ method-sampling-sample_type-low_discrepancy-digital_net-integer_format.html
__ method-sampling-sample_type-low_discrepancy-digital_net-m_max.html
__ method-sampling-sample_type-low_discrepancy-digital_net-t_max.html
__ method-sampling-sample_type-low_discrepancy-digital_net-t_scramble.html
__ method-sampling-sample_type-low_discrepancy-digital_net-generating_matrices.html
__ method-sampling-sample_type-low_discrepancy-digital_net-ordering.html



**Description**


The ``digital_net`` keyword invokes digital net sampling as the means of 
drawing samples of uncertain variables according to their probability
distributions :cite:p:`Dick10`. The Sobol sequence is a particularly 
famous example of a digital net :cite:p:`sobol67`. When this keyword is provided, it must be accompanied by the keyword :dakkw:`method-sampling-sample_type-low_discrepancy`.

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

1. Write :math:`i` in its base-:math:`b` representation, i.e., 

.. math:: 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

.. math:: \begin{pmatrix} y_1 \\ y_2 \\ y_3 \\ \vdots \end{pmatrix} = C_j \begin{pmatrix} i_1 \\ i_2 \\ i_3 \\ \vdots \end{pmatrix}

where all additions and multiplications are performed in base :math:`b`.

3. Set the :math:`j`\ th component of the :math:`i`\ th points to

.. math:: 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 :math:`C_j`, :math:`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:

- :dakkw:`method-sampling-sample_type-low_discrepancy-digital_net-generating_matrices-predefined-joe_kuo` (default): generates up to 2\ :sup:`32` points in up to 250 dimensions :cite:p:`Joe08`
- :dakkw:`method-sampling-sample_type-low_discrepancy-digital_net-generating_matrices-predefined-sobol_order_2`: generates up to 2\ :sup:`32` points in up to 1024 dimensions :cite:p:`QMCPy`

If this is not sufficient, you can provide a custom set of generating matrices 
either as an :dakkw:`method-sampling-sample_type-low_discrepancy-digital_net-generating_matrices-inline` argument, or using an external :dakkw:`method-sampling-sample_type-low_discrepancy-digital_net-generating_matrices-file`.
Custom generating matrices can be found online at :cite:p:`Kuo08`, :cite:p:`Nuyens17`.
In this case, the user must specify the ``log2`` of the maximum number of points in the 
sequence using the keyword :dakkw:`method-sampling-sample_type-low_discrepancy-digital_net-m_max`, as well as the bit depth of the generating matrices :dakkw:`method-sampling-sample_type-low_discrepancy-digital_net-t_max`.

By default, the digital points will be shifted using a digital shift vector. If :math:`\Delta` is a 
vector of standard uniform random numbers, then we compute :math:`\boldsymbol{t}^{(i)} \otimes \Delta`, where
:math:`\otimes` is the element-wise :math:`b`-ary addition operator, see :cite:p:`Dick10`.
If this is not the desired behavior, specify the keyword :dakkw:`method-sampling-sample_type-low_discrepancy-digital_net-no_digital_shift`
(**warning**: this means that the first, untransformed, point in the sequence will be 
:math:`\boldsymbol{t}^{(0)} = (0, 0, \ldots, 0)` -- this may or may not be the desired behavior :cite:p:`Owen20`.)

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 :cite:p:`Owen98` is the most well-known scrambling technique. A particular variant 
is linear matrix scrambling, which is implemented in Dakota :cite:p:`Matouvsek98`. To disable scrambling of the points, use the keyword :dakkw:`method-sampling-sample_type-low_discrepancy-digital_net-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 :math:`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 :dakkw:`method-sampling-sample_type-low_discrepancy-digital_net-ordering-gray_code`.
Use the keyword :dakkw:`method-sampling-sample_type-low_discrepancy-digital_net-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 
:cite:p:`Bratley98` 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 :cite:p:`Joe03`
and up to 21201 dimensions in :cite:p:`Joe08`. In the Dakota implementation of the algorithm outlined above, we use the iterative construction from Antonov and Saleev :cite:p:`Antonov79`.




**Examples**



.. code-block::

    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



