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

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

<b> Default Behavior </b>

The \c adjacency_matrix keyword is only relevant for \c
discrete_design_set \c real and \c discrete_design_set \c integer
variables if one or more of them have been specified to be \c
categorical.  It is always relevant for \c discrete_design_set \c
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 \ref method-mesh_adaptive_search,
which uses a tri-diagonal adjacency matrix by default.

<b> Expected Output </b>

The expected output is method dependent.

<b> Usage Tips </b>

If an adjacency matrix is defined for one type of (categorical) \c
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.

Topics::

Examples::

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

\verbatim
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'
\endverbatim

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 \c
mesh_adaptive_search, which uses a tri-diagonal adjacency matrix by
default.  Thus, the matrices used would be

\verbatim
z1: 1 1
    1 1
z2: 1 1 0
    1 1 1
    0 1 1
\endverbatim

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.

\verbatim
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
\endverbatim

Theory::
Faq::
See_Also::
method-mesh_adaptive_search
