.. _variables-active:

""""""
active
""""""


Set the active variables view a method will see



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

   variables-active-all
   variables-active-design
   variables-active-uncertain
   variables-active-aleatory
   variables-active-epistemic
   variables-active-state


**Specification**

- *Alias:* None

- *Arguments:* None

- *Default:* Infer from response or method specification


**Child Keywords:**

+-------------------------+--------------------+--------------------+-----------------------------------------------+
| Required/Optional       | Description of     | Dakota Keyword     | Dakota Keyword Description                    |
|                         | Group              |                    |                                               |
+=========================+====================+====================+===============================================+
| Required (Choose One)   | Active Variables   | `all`__            | Option for the ``active`` keyword             |
|                         |                    +--------------------+-----------------------------------------------+
|                         |                    | `design`__         | Option for the ``active`` keyword             |
|                         |                    +--------------------+-----------------------------------------------+
|                         |                    | `uncertain`__      | Option for the ``active`` keyword             |
|                         |                    +--------------------+-----------------------------------------------+
|                         |                    | `aleatory`__       | Option for the ``active`` keyword             |
|                         |                    +--------------------+-----------------------------------------------+
|                         |                    | `epistemic`__      | Option for the ``active`` keyword             |
|                         |                    +--------------------+-----------------------------------------------+
|                         |                    | `state`__          | Option for the ``active`` keyword             |
+-------------------------+--------------------+--------------------+-----------------------------------------------+

.. __: variables-active-all.html
__ variables-active-design.html
__ variables-active-uncertain.html
__ variables-active-aleatory.html
__ variables-active-epistemic.html
__ variables-active-state.html



**Description**


There are certain situations where the user may want to explicitly
control the subset of variables that is considered active for a
certain Dakota method. This is done by specifying the keyword
``active`` in the variables specification block, followed by one of the
following: ``all``, ``design``, ``uncertain``, ``aleatory``, ``epistemic``,
or ``state``.

Specifying one of these subsets of variables will allow
the Dakota method to operate on the specified variable types and
override the default active subset.

If the user does not specify any explicit override of the active view
of the variables, Dakota first considers the response function
specification.


- If the user specifies objectivefunctions or calibration terms in the response specification block,
  then we can infer that the active variables should be the design
  variables (since design variables are used within optimization and
  least squares methods).
- If the user instead specifies the genericresponse type of ``response_functions``, then
  Dakota cannot infer the active variable subset from the response
  specification and will instead infer it from the method selection.
  
  1. If the method is a parameter study, or any of the methods available under
     dace, psuade, or fsu methods, the active view is set to all
     variables.
  2. For uncertainty quantification methods, if the method is
     sampling, then the view is set to aleatory if only aleatory variables
     are present, epistemic if only epistemic variables are present, or
     uncertain (covering both aleatory and epistemic) if both are
     present.
  3. If the uncertainty method involves interval estimation or
     evidence calculations, the view is set to epistemic.
  4. For other uncertainty quantification methods not mentioned in the previous
     sentences (e.g., reliability methods or stochastic expansion methods),
     the default view is set to aleatory.
  5. Finally, for verification studies
     using the Richardson extrapolation method, the active view is set to
     state.
  6. Note that in surrogate-based optimization, where the surrogate
     is built on points defined by the method defined by the
     ``dace_method_pointer``, the sampling used to generate the points
     is performed only over the design variables as a default unless
     otherwise specified (e.g. state variables will not be sampled
     for surrogate construction).

As alluded to in the previous section, the iterative method selected
for use in Dakota determines what subset, or view, of the variables
data is active in the iteration. The general case of having a mixture
of various different types of variables is supported within all of the
Dakota methods even though certain methods will only modify certain
types of variables (e.g., optimizers and least squares methods only
modify design variables, and uncertainty quantification methods
typically only utilize uncertain variables).
This implies that variables which are not under the
direct control of a particular iterator will be mapped through the
interface in an unmodified state. This allows for a variety of
parameterizations within the model in addition to those which are
being used by a particular iterator, which can provide the convenience
of consolidating the control over various modeling parameters in a
single file (the Dakota input file). An important related point is
that the variable set that is active with a particular iterator is the
same variable set for which derivatives are typically computed.




**Examples**


For example, the default behavior
for a nondeterministic sampling method is to sample the uncertain
variables. However, if the user specifed ``active all`` in the
variables specification block, the sampling would be performed over
all variables (e.g. design and state variables in addition to the
uncertain variables). This may be desired in situations such as
surrogate-based optimization under uncertainty, where a surrogate may
be constructed to span both design and uncertain variables. This is
an example where we expand the active subset beyond the default, but
in other situations, we may wish to restrict from the default. An
example of this would be performing design of experiments in the
presence of multiple variable types (for which all types are active by
default), but only wanting to sample over the design variables for
purposes of constructing a surrogate model for optimization.




**Theory**


The optional status of the different variable type specifications
allows the user to specify only those variables which are present
(rather than explicitly specifying that the number of a particular
type of variables is zero). However, at least one type of variables
that are active for the iterator in use must have nonzero size or an
input error message will result.