Adjacency set documentation is obtuse / not helpful.

I read through the doc for adjacency sets and it did not help me understand them. I think it needs to include more of the motivation for why these are needed and walk through an example of how to construct one and what it means to make one.

Some ideas:

Adjacency sets identify regions of a local domain that touch other domains, when meshes are decomposed into multiple domains. Adjacency sets can be used to help guide interprocessor communication when running in parallel. A common use case is to identify the vertices in a domain that touch adjacent domains. Such vertices can be added into a group within an adjacency set that contains vertices that touch a set of neighboring domains.

In the local domain where this adjset is defined, all of the local vertex ids correspond to vertices from the local coordset. The adjacency set group contains a values array that stores the local vertex ids that touch an external domain's vertices. In the example below, vertices [4,5,9,23] all touch domain 0, according to the neighbors list. The vertices they touch in domain 0 will have different vertex ids in domain 0 as they may be defined in a different order within domain 0's coordset.

adjsets: 
  main_adjset: 
    association: "vertex"
    topology: "main"
    groups: 
      group_0_1: 
        neighbors: 0
        values: [4, 5, 9, 23]

The example below shows two adjacency set groups where the vertices abut different domains. The vertices in the group_1_2 group set (the values) match with vertices in domain 2 (neighbors). In the second group set, group_0_1_3, vertices (the values) [0, 1, 8, 10, 22] in the local domain will be matched with vertices in domain 0 and domain 3 since the neighbors list contains [0,3].

adjsets: 
  main_adjset: 
    association: "vertex"
    topology: "main"
    groups: 
      group_1_2: 
        neighbors: 2
        values: [15, 17, 19, 21]
      group_0_1_3: 
        neighbors: [0, 3]
        values: [0, 1, 8, 10, 22]

Give 2-3 domain example with pictures
Discuss paint_adjset and how to use it to show adjsets are right

LLNL / conduit

Adjacency set documentation is obtuse / not helpful. #1098