Blurb::
Randomly samples variables according to their distributions

Description::
This method generates parameter values by drawing samples from the
specified uncertain variable probability distributions. The
computational model is executed over all generated parameter values to
compute the responses for which statistics are computed. The
statistics support sensitivity analysis and uncertainty
quantification.

<b> Default Behavior </b>

By default, \c sampling methods operate on aleatory and epistemic
uncertain variables.  The types of variables can be restricted or
expanded (to include design or state variables) through use of the
\c active keyword in the \ref variables block in the Dakota input
file.  If continuous design and/or state variables are designated as
active, the sampling algorithm will treat them as parameters with
uniform probability distributions between their upper and lower
bounds.  Refer to \ref topic-variable_support for additional 
information on supported variable types, with and without correlation.

The following keywords change how the samples are selected:
\li sample_type
\li fixed_seed
\li rng
\li samples
\li seed
\li variance_based_decomp

<b> Expected Outputs </b>

As a default, %Dakota provides correlation analyses when running LHS.
Correlation tables are printed with the simple, partial, and rank
correlations between inputs and outputs. These can be useful to get a
quick sense of how correlated the inputs are to each other, and how
correlated various outputs are to inputs. \c variance_based_decomp is
used to request more sensitivity information, with additional cost.

Additional statistics can be computed from the samples using the following
keywords:
\li \c response_levels
\li \c reliability_levels
\li \c probability_levels     
\li \c gen_reliability_levels 

\c response_levels computes statistics at the specified response value.
The other three allow the specification of the statistic value, and will
estimate the corresponding response value.

\c distribution is used to specify whether the statistic values are 
from cumulative or complementary cumulative functions.

<b> Expected HDF5 Output </b>

If Dakota was built with HDF5 support and run with the 
\ref environment-results_output-hdf5 keyword, this method
writes the following results to HDF5:

- When \ref method-sampling-variance_based_decomp is enabled
  - \ref hdf5_results-vbd 
- For aleatory UQ studies
  - \ref hdf5_results-pdf
  - \ref hdf5_results-level_mappings
  - \ref hdf5_results-sampling_moments
  - \ref hdf5_results-correlations
- For epistemic UQ studies
  - \ref hdf5_results-extreme_responses
  - \ref hdf5_results-correlations

<b> Usage Tips </b>

\c sampling is a robust approach to doing sensitivity analysis and
uncertainty quantification that can be applied to any problem.  It
requires more simulations than newer, advanced methods.  Thus, an
alternative may be preferable if the simulation is computationally
expensive.

<!---
Normally, \c sampling generates samples only for the 
uncertain variables, and
treats any design or state variables as constants. 
However, if \c active \c all is specified in the variables block, 
sampling will be performed over all variables, including 
uncertain, design, and state. 
In this case, the sampling 
algorithm will treat any continuous design or continuous state variables
as parameters with uniform probability distributions between their
upper and lower bounds. Samples are then generated over all of the
continuous variables (design, uncertain, and state) in the variables
specification. 

This is similar to the behavior of the design of
experiments methods, since they will also
generate samples over all continuous design, uncertain, and state
variables in the variables specification. 
However, the design of
experiments methods will treat all variables as being uniformly
distributed between their upper and lower bounds, whereas the \c
sampling method will sample the uncertain variables within
their specified probability distributions. 

If further 
granularity of sampling is necessary for uncertain variables, 
one can specify \c active \c epistemic or \c active \c aleatory 
to specify sampling over only epistemic uncertain or 
only aleatory uncertain variables, respectively. 
In the case where one wants to generate samples only over 
state variables, one would specify \c active \c state in the 
variables specification block. 
--->
Topics::	uncertainty_quantification, sampling	
Examples::
\verbatim
# tested on Dakota 6.0 on 140501

environment
  tabular_data
    tabular_data_file = 'Sampling_basic.dat'

method
  sampling
    sample_type lhs
    samples = 20

model
  single

variables
  active uncertain
  uniform_uncertain = 2
    descriptors  =   'input1'     'input2'
    lower_bounds =  -2.0     -2.0
    upper_bounds =   2.0      2.0
  continuous_state = 1
    descriptors =   'constant1'
    initial_state = 100

interface
  analysis_drivers 'text_book'
    fork

responses
  response_functions = 1
  no_gradients
  no_hessians
\endverbatim

This example illustrates a basic sampling Dakota input file.

\li LHS is used instead of purely random sampling.
\li The default random number generator is used.
\li Without a \c seed specified, this will not be reproducable
\li In the \c variables block, two types of variables are used
\li Only the uncertain variables are varied, this is the default 
    behavior, and is also specified by the \c active keyword, w/ the
    \c uncertain option

Theory::
Faq::
<b>Q: </b> Do I need to keep the LHS* and S4 files?
<b>A: </b> No

See_Also::	variables-active
