.. _variables-uncertain_correlation_matrix: """""""""""""""""""""""""""" uncertain_correlation_matrix """""""""""""""""""""""""""" Correlation among aleatory uncertain variables **Specification** - *Alias:* None - *Arguments:* None - *JSON argument key:* None **Description** Aleatory uncertain variables may have correlations specified through use of an ``uncertain_correlation_matrix`` specification. This specification is generalized in the sense that its specific meaning depends on the nondeterministic method in use. When the method is a nondeterministic sampling method (i.e., :dakkw:`method-sampling`), then the correlation matrix specifies *rank correlations* :cite:p:`Iman1982`. When the method is a reliability (i.e., :dakkw:`method-local_reliability` or :dakkw:`method-global_reliability`) or stochastic expansion (i.e., :dakkw:`method-polynomial_chaos` or :dakkw:`method-stoch_collocation`) method, then the correlation matrix specifies *correlation coefficients* (normalized covariance) :cite:p:`Hal00`. In either of these cases, specifying the identity matrix results in uncorrelated uncertain variables (the default). The matrix input should be symmetric and have all :math:`n^2` entries where *n* is the total number of aleatory uncertain variables. Ordering of the aleatory uncertain variables is as shown in the input-specification-ordered table in :dakkw:`variables` for ``normal``, ``lognormal``, ..., ``histogram_point``. .. TODO: What does the following statement mean? When additional variable types are activated, they assume uniform distributions, and the ordering is as listed on :dakkw:`variables`. **Examples** Consider the following random variables, distributions and correlations: - :math:`X_1` , normal, uncorrelated with others - :math:`X_2` , normal, correlated with :math:`X_3` , :math:`X_4` and :math:`X_5` - :math:`X_3` , weibull , correlated with :math:`X_5` - :math:`X_4` , exponential, correlated with :math:`X_3` , :math:`X_4` and :math:`X_5` - :math:`X_5` , normal, correlated with :math:`X_5` These correlations are captured by the following commands (order of the variables is respected). .. tab:: Freeform .. code-block:: dakota variables normal_uncertain = 2 means = 0.0 0.0 std_deviations = 1.0 1.0 exponential_uncertain = 1 betas = 1.0 weibull_uncertain = 1 alphas = 2.0 betas = 1.0 uncertain_correlation_matrix # ordering normal, exponential, weibull # X_1 X_2 X_5 X_4 X_3 1.00 0.00 0.00 0.00 0.00 0.00 1.00 0.50 0.24 0.78 0.00 0.50 1.00 0.00 0.20 0.00 0.24 0.00 1.00 0.49 0.00 0.78 0.20 0.49 1.00 .. tab:: JSON .. code-block:: json { "variables": [ { "normal_uncertain": { "count": 2, "means": [0.0, 0.0], "std_deviations": [1.0, 1.0] }, "uncertain_correlation_matrix": [ 1.00, 0.78, 0.78, 1.00 ] } ] }