.. _method-list_parameter_study:

""""""""""""""""""""
list_parameter_study
""""""""""""""""""""


Samples variables as a specified values



**Topics**


parameter_studies


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

   method-list_parameter_study-list_of_points
   method-list_parameter_study-import_points_file
   method-list_parameter_study-model_pointer


**Specification**

- *Alias:* None

- *Arguments:* None


**Child Keywords:**

+-------------------------+--------------------+------------------------+---------------------------------------------+
| Required/Optional       | Description of     | Dakota Keyword         | Dakota Keyword Description                  |
|                         | Group              |                        |                                             |
+=========================+====================+========================+=============================================+
| Required (Choose One)   | Points Source      | `list_of_points`__     | List of variable values to evaluate in a    |
|                         |                    |                        | list parameter study                        |
|                         |                    +------------------------+---------------------------------------------+
|                         |                    | `import_points_file`__ | File containing list of variable values to  |
|                         |                    |                        | evaluate in a list parameter study          |
+-------------------------+--------------------+------------------------+---------------------------------------------+
| Optional                                     | `model_pointer`__      | Identifier for model block to be used by a  |
|                                              |                        | method                                      |
+----------------------------------------------+------------------------+---------------------------------------------+

.. __: method-list_parameter_study-list_of_points.html
__ method-list_parameter_study-import_points_file.html
__ method-list_parameter_study-model_pointer.html



**Description**


Dakota's list parameter study allows for evaluations at user selected
points of interest.

*Default Behavior*

By default, the list parameter study operates over all types of
variables.

The number of real values in the ``list_of_points`` specification or
file referenced by ``import_points_file`` must be a multiple of the
total number of variables (including continuous and discrete types)
contained in the variables specification.

*Expected Outputs*

A list parameter study produces a set of responses for each parameter
set that is specified.

*Expected HDF5 Output*

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


- :ref:`hdf5_results-pstudies`


*Usage Tips*


- This parameter study simply   performs simulations for the first parameter set (the first ``n``   entries in the list), followed by the next parameter set (the next   ``n`` entries), and so on, until the list of points has been   exhausted.
- Since the initial values from the variables specification   will not be used, they need not be specified.
- When the points are specified in the Dakota input file using the    ``list_of_points`` keyword, discrete set values must be referred to using 0-based   indexes, and not the values themselves. However, when using ``import_points_file``,   refer to discrete set values directly, not by index.
- For both ``list_of_points`` and ``import_points_file``, Dakota expects the values for each evaluation to be ordered by type. The type ordering matches that of the :dakkw:`variables` section
  and of the listing in the :ref:`Parameters file format section <variables:parameters>`. When multiple variables are present for a single type, the ordering within that type must match
  the order specified by the user in the variables section of her input file.



**Examples**


This shows the method and variables block of a Dakota input file
that runs a list_parameter_study.

.. code-block::

    method
      list_parameter_study
        list_of_points =
                     3.1e6    0.0029    0.31
                     3.2e6    0.0028    0.32
                     3.3e6    0.0027    0.34
                     3.3e6    0.0026    0.36
    
    variables
      continuous_design = 3
        descriptors = 'E'    'MASS'     'DENSITY'
    


Note that because of the way Dakota treats whitespace, the above example is equivalent to:

.. code-block::

    method
      list_parameter_study
        list_of_points =
    3.1e6    0.0029    0.31  3.2e6    0.0028
    0.32    3.3e6    0.0027
    0.34  3.3e6    0.0026    0.36
    
    variables
      continuous_design = 3
        descriptors = 'E'  'MASS'   'DENSITY'

Although the first example is much more readable.

And here's a full input file:


.. code-block::

    # tested on Dakota 6.0 on 140501
    environment
      tabular_data
        tabular_data_file 'List_param_study.dat'
    
    method
      list_parameter_study
        list_of_points =     0.1    0.1
                             0.2    0.1
                             0.3    0.0
                             0.3    1.0
    
    model
      single
    
    variables
      active design
      continuous_design = 2
        descriptors    'x1' 'x2'
      continuous_state = 1
        descriptors =   'constant1'
        initial_state = 100
    
    interface
      analysis_drivers 'text_book'
        fork
      asynchronous
        evaluation_concurrency 2
    
    responses
      response_functions = 1
      no_gradients
      no_hessians
    


This example illustrates the list_parameter_study.


- The function evaluations are independent, so any level of     ``evaluation_concurrency`` can be used
- Default behavior for parameter studies is to iterate on all variables.     However, because ``active`` ``design`` is specified, this study will only     iterate on the ``continuous_design`` variables.