Blurb::
Uses digital net points to sample variables

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`.

Topics::

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

Theory::

Faq::

See_Also::
