.. _model-active_subspace:

"""""""""""""""
active_subspace
"""""""""""""""


Active (variable) subspace model


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

   model-active_subspace-truth_model_pointer
   model-active_subspace-initial_samples
   model-active_subspace-sample_type
   model-active_subspace-truncation_method
   model-active_subspace-dimension
   model-active_subspace-bootstrap_samples
   model-active_subspace-build_surrogate
   model-active_subspace-normalization


**Specification**

- *Alias:* subspace 

- *Arguments:* None


**Child Keywords:**

+-------------------------+--------------------+-------------------------+-----------------------------------------------+
| Required/Optional       | Description of     | Dakota Keyword          | Dakota Keyword Description                    |
|                         | Group              |                         |                                               |
+=========================+====================+=========================+===============================================+
| Required                                     | `truth_model_pointer`__ | Pointer to specify a full-space model, from   |
|                                              |                         | which to construct a lower dimensional        |
|                                              |                         | surrogate                                     |
+----------------------------------------------+-------------------------+-----------------------------------------------+
| Optional                                     | `initial_samples`__     | Initial number of samples for sampling-based  |
|                                              |                         | methods                                       |
+----------------------------------------------+-------------------------+-----------------------------------------------+
| Optional                                     | `sample_type`__         | Selection of sampling strategy                |
+----------------------------------------------+-------------------------+-----------------------------------------------+
| Optional                                     | `truncation_method`__   | Metric that estimates active subspace size    |
+----------------------------------------------+-------------------------+-----------------------------------------------+
| Optional                                     | `dimension`__           | Explicitly specify the desired subspace size  |
+----------------------------------------------+-------------------------+-----------------------------------------------+
| Optional                                     | `bootstrap_samples`__   | Number of bootstrap replicates used in        |
|                                              |                         | truncation metrics                            |
+----------------------------------------------+-------------------------+-----------------------------------------------+
| Optional                                     | `build_surrogate`__     | Construct moving least squares surrogate over |
|                                              |                         | active subspace                               |
+----------------------------------------------+-------------------------+-----------------------------------------------+
| Optional                                     | `normalization`__       | Normalize gradient samples                    |
+----------------------------------------------+-------------------------+-----------------------------------------------+

.. __: model-active_subspace-truth_model_pointer.html
__ model-active_subspace-initial_samples.html
__ model-active_subspace-sample_type.html
__ model-active_subspace-truncation_method.html
__ model-active_subspace-dimension.html
__ model-active_subspace-bootstrap_samples.html
__ model-active_subspace-build_surrogate.html
__ model-active_subspace-normalization.html



**Description**


A model that transforms the original model (given by
:dakkw:`model-active_subspace-truth_model_pointer`) to one with a reduced set of variables.  This
reduced model is identified by iteratively sampling the gradient of
the original model and performing a singular value decomposition of
the gradient matrix.

*Expected Output*

A subspace model will perform an initial sampling design to
identify an active subspace using one of the truncation methods.

*Usage Tips*

If the desired subspace size is not identified, consider using the explicit
:dakkw:`model-active_subspace-dimension` truncation option or one of the other truncation methods.



**Examples**


Perform an initial 100 gradient samples and use the :dakkw:`model-active_subspace-truncation_method-bing_li`
truncation method to identify an active subspace. The truncation method uses 150 bootstrap samples
to compute the Bing Li truncation metric.


.. code-block::

    model
      subspace
        id_model = 'SUBSPACE'
        truth_model_pointer = 'FULLSPACE'
        initial_samples  100
        truncation_method bing_li
        bootstrap_samples 150





**Theory**


The idea behind active subspaces is to find directions in the input variable
space in which the quantity of interest is nearly constant. After rotation of
the input variables, this method can allow significant dimension reduction. Below is a brief summary of the process.

1. Compute the gradient of the quantity of interest, :math:`q = f(\mathbf{x})` ,
    at several locations sampled from the full input space,
    
.. math:: \nabla_{\mathbf{x}} f_i = \nabla f(\mathbf{x}_i).

2. Compute the eigendecomposition of the matrix :math:`\hat{\mathbf{C}}` ,

.. math:: \hat{\mathbf{C}} = \frac{1}{M}\sum_{i=1}^{M}\nabla_{\mathbf{x}} f_i\nabla_{\mathbf{x}} f_i^T = \hat{\mathbf{W}}\hat{\mathbf{\Lambda}}\hat{\mathbf{W}}^T,

where :math:`\hat{\mathbf{W}}`  has eigenvectors as columns,
    :math:`\hat{\mathbf{\Lambda}} = \text{diag}(\hat{\lambda}_1,\:\ldots\:,\hat{\lambda}_N)` 
    contains eigenvalues, and :math:`N`  is the total number of parameters.

3. Using a :dakkw:`model-active_subspace-truncation_method` or specifying a
    :dakkw:`model-active_subspace-dimension` to estimate the active subspace size,
    split the eigenvectors into active and inactive directions,
    
.. math:: \hat{\mathbf{W}} = \left[\hat{\mathbf{W}}_1\quad\hat{\mathbf{W}}_2\right].

These eigenvectors are used to rotate the input variables.

4. Next the input variables, :math:`\mathbf{x}` , are expanded in terms of active and
    inactive variables,
    
.. math:: \mathbf{x} = \hat{\mathbf{W}}_1\mathbf{y} + \hat{\mathbf{W}}_2\mathbf{z}.

5. A surrogate is then built as a function of the active variables,
    
.. math:: g(\mathbf{y}) \approx f(\mathbf{x})

For additional information, see:

1. Constantine, Paul G. "Active Subspaces: Emerging Ideas for Dimension Reduction in Parameter Studies". Vol. 2. SIAM, 2015.

2. Constantine, Paul G., Eric Dow, and Qiqi Wang. "Active subspace methods in theory and practice: Applications to kriging surfaces." SIAM Journal on Scientific Computing 36.4 (2014): A1500-A1524.

3. Constantine, Paul, and David Gleich. "Computing Active Subspaces." arXiv preprint arXiv:1408.0545 (2014).


