.. _method-sampling-sample_type-low_discrepancy-rank_1_lattice-ordering:

""""""""
ordering
""""""""


Ordering of the points of this rank-1 lattice



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

   method-sampling-sample_type-low_discrepancy-rank_1_lattice-ordering-natural
   method-sampling-sample_type-low_discrepancy-rank_1_lattice-ordering-radical_inverse


**Specification**

- *Alias:* None

- *Arguments:* None

- *Default:* Radical inverse ordering


**Child Keywords:**

+-------------------------+--------------------+---------------------+-----------------------------------------------+
| Required/Optional       | Description of     | Dakota Keyword      | Dakota Keyword Description                    |
|                         | Group              |                     |                                               |
+=========================+====================+=====================+===============================================+
| Required (Choose One)   | Ordering           | `natural`__         | Natural ordering of the points of this rank-1 |
|                         |                    |                     | lattice                                       |
|                         |                    +---------------------+-----------------------------------------------+
|                         |                    | `radical_inverse`__ | Radical inverse ordering of the points of     |
|                         |                    |                     | this rank-1 lattice                           |
+-------------------------+--------------------+---------------------+-----------------------------------------------+

.. __: method-sampling-sample_type-low_discrepancy-rank_1_lattice-ordering-natural.html
__ method-sampling-sample_type-low_discrepancy-rank_1_lattice-ordering-radical_inverse.html



**Description**


Specify the order in which the points of this rank-1 lattice should be returned. 
Currently, Dakota supports :dakkw:`method-sampling-sample_type-low_discrepancy-rank_1_lattice-ordering-natural` and :dakkw:`method-sampling-sample_type-low_discrepancy-rank_1_lattice-ordering-radical_inverse` ordering. 
The default behavior is to return points using radical inverse ordering, i.e., 
the points will be generated according to

.. math:: \boldsymbol{t}^{(i)} = \left\{ \phi_b(i) \boldsymbol{z} \right\}

where :math:`\phi_b(i)` denotes the so-called *radical inverse* function in base :math:`b` (usually, and also in Dakota, :math:`b = 2`). 
This function transforms a number :math:`i = (\ldots i_2i_1)_b` in its base-:math:`b` representation 
to :math:`\phi_b(i) = (0.i_1i_2\ldots)_b`. Note that the radical inverse function agrees with the original 
formulation when :math:`N = b^m` for any :math:`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 :math:`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*.

*Usage Tips*

When the :dakkw:`method-sampling-sample_type-low_discrepancy-rank_1_lattice-ordering-natural` ordering of the points is used, it is implicitly assumed that the user will 
only request a number of points that is a power of 2. Failing to do so will result in a set of points 
for which one or more dimensions are not uniformly covered, resulting in bad low-discrepancy properties, 
and ultimately bad performance of the method that uses these points. It is recommended to not use this option unless you know what you're doing.




**Examples**



.. code-block::

    environment
      tabular_data
        tabular_data_file = 'samples.dat'
        freeform

    method
      sampling
        samples 8
        sample_type
          low_discrepancy
            rank_1_lattice
              generating_vector inline 1 5 # this is a Fibonacci lattice
              m_max 3 # 8 points in total
              no_random_shift
              ordering natural

    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



