.. _variables-discrete_design_set-string-adjacency_matrix:

""""""""""""""""
adjacency_matrix
""""""""""""""""


1-0 matrix defining which categorical variable levels are related.


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



**Specification**

- *Alias:* None

- *Arguments:* INTEGERLIST


**Description**


The ``adjacency_matrix`` keyword is associated with
``discrete_design_set`` variables that are specified to be categorical. Each
such variable is associated with one :math:`k \times k`  symmetric matrix, where
:math:`k`  is the number of values (or levels) of the variable. Entry :math:`i,j`  of
a matrix should be 1 if level :math:`i`  and level :math:`j` 
are related by some subjective criteria or if :math:`i=j` ; it should be
0 otherwise. The matrices for all variables of the same type ( ``string``,
``real``, or ``integer``) are entered sequentially as a list of integers as
shown in the examples below.

*Default Behavior*

The ``adjacency_matrix`` keyword is only relevant for
``discrete_design_set`` ``real`` and ``discrete_design_set`` ``integer``
variables if one or more of them have been specified to be
``categorical``.  It is always relevant for ``discrete_design_set``
``string`` variables.  If the user does not define an adjacency matrix,
the default is method dependent.  Currently, the only method that
makes use of the adjacency matrix is :dakkw:`method-mesh_adaptive_search`,
which uses a tri-diagonal adjacency matrix by default.

*Expected Output*

The expected output is method dependent.

*Usage Tips*

If an adjacency matrix is defined for one type of (categorical)
``discrete_design_set`` variable, if must be defined for all variables of
that type, even for those not defined to be categorical.  Those for
the non-categorical set variables will be ignored.



**Examples**


The following example shows a variables specification where some real
and some integer ``discrete_design_set`` variables are categorical.


.. code-block::

    variables
      continuous_design = 3
        initial_point  -1.0    1.5   2.0
        lower_bounds  -10.0  -10.0 -10.0
        upper_bounds   10.0   10.0  10.0
        descriptors    'x1'   'x2'  'x3'
      discrete_design_range = 2
        initial_point  2     2
        lower_bounds   1     1
        upper_bounds   4     9
        descriptors   'y1'  'y2'
      discrete_design_set
        real = 2
          elements_per_variable = 4 5
          elements  =  1.2 2.3 3.4 4.5 1.2 3.3 4.4 5.5 7.7
          descriptors  'y3'            'y4'
          categorical  'no'            'yes'
          adjacency_matrix 1 1 0 0  # Begin entry of 4x4 matrix for y3
                           1 1 1 0
                           0 1 1 1
                           0 0 1 1
                           1 0 1 0 1 # Begin entry of 5x5 matrix for y4
                           0 1 0 1 0
                           1 0 1 0 1
                           0 1 0 1 0
                           1 0 1 0 1
        integer = 2
          elements_per_variable = 2 3
          elements  =  4  7  8  9  12
          descriptors  'z1'  'z2'
          categorical  'yes' 'yes'


Note that for the real case, the user wants to define an adjacency
matrix for the categorical variable, so adjacency matrices for both
variables must be specified.  The matrix for the first one will be
ignored.  Note that no adjacency matrix is specified for either
integer categorical variable.  The default will be used in both cases.
Currently the only method taking advantage of adjacency matrices is
``mesh_adaptive_search``, which uses a tri-diagonal adjacency matrix by
default.  Thus, the matrices used would be


.. code-block::

    z1: 1 1
        1 1
    z2: 1 1 0
        1 1 1
        0 1 1


The following example shows a variables specification for string
variables.  Note that string variables are always considered to be
categorical.  If an adjacency matrix is not specified, a
method-dependent default matrix will be used.


.. code-block::

    variables,
      continuous_design = 2
        initial_point  0.5  0.5
        lower_bounds   0.   0.
        upper_bounds   1.   1.
        descriptors =  'x'  'y'
      discrete_design_set string = 1
        elements = 'aniso1' 'aniso2' 'iso1' 'iso2' 'iso3'
        descriptors = 'ancomp'
        adjacency_matrix 1 1 0 0 0
                         1 1 0 0 0
                         0 0 1 1 1
                         0 0 1 1 1
                         0 0 1 1 1