.. _method-sampling-sample_type-low_discrepancy:

"""""""""""""""
low_discrepancy
"""""""""""""""


Uses low-discrepancy points to sample variables



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

   method-sampling-sample_type-low_discrepancy-rank_1_lattice
   method-sampling-sample_type-low_discrepancy-digital_net


**Specification**

- *Alias:* qmc 

- *Arguments:* None


**Child Keywords:**

+-------------------------+--------------------+--------------------+-----------------------------------------------+
| Required/Optional       | Description of     | Dakota Keyword     | Dakota Keyword Description                    |
|                         | Group              |                    |                                               |
+=========================+====================+====================+===============================================+
| Optional                                     | `rank_1_lattice`__ | Uses rank-1 lattice points to sample          |
|                                              |                    | variables                                     |
+----------------------------------------------+--------------------+-----------------------------------------------+
| Optional                                     | `digital_net`__    | Uses digital net points to sample variables   |
+----------------------------------------------+--------------------+-----------------------------------------------+

.. __: method-sampling-sample_type-low_discrepancy-rank_1_lattice.html
__ method-sampling-sample_type-low_discrepancy-digital_net.html



**Description**


The ``low_discrepancy`` keyword invokes low-discrepancy sampling as the means of
drawing samples of uncertain variables according to their probability
distributions. Low-discrepancy points have the desired property that they are 
more evenly distributed compared to random samples. We implement two flavors 
of low-discrepancy points: :dakkw:`method-sampling-sample_type-low_discrepancy-rank_1_lattice` points :cite:p:`Nuyens06` and 
:dakkw:`method-sampling-sample_type-low_discrepancy-digital_net`\ s :cite:p:`Joe08`. Digital net points are the 
default choice. The well-known Sobol sequence is a particular example of a digital net :cite:p:`sobol67`.

When low-discrepancy points are used for integration, the method is called the 
quasi-Monte Carlo method. Low-discrepancy points are also referred to as 
quasi-Monte Carlo points.

.. note::
   Currently, only continuous variables are suppored for low discrepancy
   sampling.

*Usage Tips*

Low-discrepancy points easily scale up to hundreds or thousands of dimensions. 
They are generally more efficient than random samples (and sometimes more 
efficient than Latin Hypercube samples) for estimating the mean of a model 
response. Digital net sequences (such as the Sobol sequence) can even achieve 
higher-order convergence :cite:p:`Dick10`.

Quasi-Monte Carlo points work best if the random variables in the model are ordered according to 
their relative importance, i.e., the first variable in the model is the most 
important, the second one is less important, and so on, and if the importance 
of the random variables decays relatively rapidly. In modern quasi-Monte Carlo 
literature, this is understood as if the function belongs to a function class 
with a certain *smoothness* :cite:p:`Joe08`.

Just as Latin Hypercube samples, the low-discrepancy points are generated 
uniformly in the unit (hyper)cube and care must be taken when the points are 
transformed to other distributions. For example, when generating standard 
normally distributed samples, the points are mapped from the unit cube to 
an infinite domain using the inverse cumulative distribution function. This 
function becomes unbounded near the boundary, which makes it hard to 
integrate, and one may lose the high-order convergence observed when 
integrating in the (hyper)cube :cite:p:`Dick13`.




**Examples**



.. code-block::

    environment
      tabular_data
        tabular_data_file = 'samples.dat'
        freeform

    method
      sampling
        samples 32
        sample_type
          low_discrepancy

    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