# Connected components

VisIt provides an expression and set of queries to help identify and summarize connected subcomponents of a mesh. The connected components algorithm used is unique in that it can not only process simple meshes, but it can also efficiently handle large data parallel meshes. This page gives an overview of how to use VisIt's connected components capability. (The algorithm is not discussed here)

## Contents

## Connected Components Expression

The core of VisIt's connected components functionality is provided by a filter encapsulated by the "conn_components" expression. This expression takes a mesh name and an optional flag controlling a Ghost Zone Neighbors Communication Enhancement (outlined below). The expression creates unique labels for each connected mesh subcomponent and tags each zone in the mesh with the label of the connected component it belongs to. Because it labels each zone with its component id, it is often referred to as Connected Components Labeling (CCL).

#### Expression Syntax

To define a connected components expression use the following syntax, where *<Mesh>* is the name of your dataset's mesh object.

conn_components(<Mesh>) # Attempt to use Ghost Zone Neighbors Enhancement (Default) conn_components(<Mesh>,0) # Do not use Ghost Zone Neighbors Enhancement conn_components(<Mesh>,1) # Attempt to use Ghost Zone Neighbors Enhancement

#### Ghost Zone Neighbors Communication Enhancement

In the parallel case of the algorithm the mesh is spatially redistributed to determine connectivity. In many cases ghost zones completely encapsulate connectivity across domains and can be used to greatly reduce the amount of data that needs to be redistributed.

By default the expression *conn_components(<Mesh>)* attempts to use this enhancement, and is equivalent to *conn_components(<Mesh>,1)*.
If ghost zones for your mesh do not provide enough connectivity info to resolve the components, you can disable this enhancement
by defining the expression as *conn_components(<Mesh>,0)*. In the parallel case this will result in a full spatial redistribution to resolve connectivity. In VisIt 1.11 the expression provides stronger checks for valid ghost zones, particularly for AMR data.

## Connected Components Related Queries

VisIt also provides several queries that summarize info about connected components.

#### Query Overview

Query | Purpose |

Number of Connected Components | Returns the number of connected components found. |

Connected Component Centroids | Returns the centroid location (x,y,z) for each connected component. |

Connected Component Area | Returns the area of each connected component. (2D Meshes only) |

Connected Component Volume | Returns the volume of each connected component. (3D or RZ Meshes only) |

Connected Component Variable Sum | Sums up the scalar input value of each zone per connected component. |

Connected Component Weighted Variable Sum | Weights scalar input variable by an appropriate zone volume and sums up these results per connected component.
For example: To compute the mass of each component you can create a density plot and the weighted variable sum will multiply the density by the proper volume calculation (area, revolved volume, or volume) producing mass per zone. The query will then sum up the zone masses for each connected component to obtain a component mass. |

Connected Components Summary | Where appropriate, computes and aggregates all of the above results. See Connected Components Summary Details for further info. |

### Connected Components Summary Details

The Connected Components Summary query computes and aggregates all component info and optionally writes this data to an okc file (an XMDF File format - For a brief overview Xmdv files see Using Xmdv Files) The okc output provides an entry per component with the following data fields:

Component Data | Fields |

Centroid | comp_x, comp_y, comp_z |

Component Id | comp_label |

Number of Cells (or Zones) per component | comp_num_cells |

Area (if the dataset is 2D) | comp_area |

Volume (if the dataset is 3D or RZ) | comp_volume |

Variable Sum | comp_sum |

Weighted Variable Sum | comp_weighted_sum |

VisIt can read this okc file as point data allowing you to plot component centroid locations and component values. The result points are always 3D (comp_z will equal 0 for 2D datasets) so if you wish to plot them over a 2D dataset you will need to use the Project operator. The okc results are very simple to parse, so post processing in python or other languages is an option.

Direct access to these results is also available in the CLI via GetQueryOutputValue() which returns a packed double array.

The result array has the following 9 values per entry (# of components equals len(result_array)/9):

comp_x, comp_y, comp_z, comp_label, comp_num_cells, comp_area, comp_volume, comp_sum, comp_weighted_sum

Zero is used as a default for comp_area & comp_volume if not applicable (For example, for a 2D non RZ dataset - volume is not calculated)

## Detailed Examples

#### Using the conn_components Expression

It is important to remember that VisIt typically evaluates expressions at the beginning of its processing pipeline. So if you have a solid mesh and alter it with an operator (say Isovolume) and try to plot connected component labels you will end up with a single label. To force VisIt to postpone expression evaluation until have you have altered the mesh you need to use the DeferExpression Operator.

Here is a simple example that demonstrates this process:

- Open rect2d.silo
- Define two scalar expressions:

ccl = conn_components(quadmesh2d) random_value = rand(quadmesh2d)

- Create a Pseudocolor Plot of
*ccl* - Add an Isovolume Operator, set variable=
*random_value*and minimum=.5 - Add a DeferExpression Operator and add
*ccl*to the expression list (If you do not see this operator, you may need to enable it) - Click Draw

The resulting mesh will be colored by component label. Depending on your colormap some components may look similar. You may want
to create a Label plot of *ccl* with the same operators to help you view component labels.

#### Using the Connected Components Summary Query

Here is an example of creating a histogram of the mass of connected mesh components.

- Open rect2d.silo
- If have not defined the
*random_value*expression, create it as in the example above. - Create a Pseudocolor Plot of
*d*(our density variable) - Add an Isovolume Operator, set variable=
*random_value*and minimum=.5 - Click Draw
- Execute a "Connected Components Summary Query"

At this point a file named cc_summary.okc is created, you should also receive a message that 89 connected components were found.

- Create a new VisIt window
- Open cc_summary.okc
- Create a Histogram plot of
*comp_weighted_sum*

You should see the histogram below, giving you a sense there are several small components and a few large ones.

#### Evaluating aggregate values over the Connected Components

You may wish to evaluate global values, such as the accumulated area of each cell forming the connected components. VisIt has an aggregator operator called *key_agg*. You will need to define two more expressions:

- DefineScalarExpression('area', 'area(quadmesh2d)')
- DefineScalarExpression('total_area', 'key_agg(ccl, area)')
- Go back to your DeferExpression Operator and add
*area*and*total_area*to the expression list - The area of each connected component is now evaluated. You can pseudo-color, threshold, etc... using
*total_area*as a variable name

## Advanced Details

What connectivity tests are supported? Sparing the details of the entire algorithm there are two important connectivity tests used:

- With in a mesh (typically a domain) we use the connectivity of the vtk cells, meaning cells that share nodes are connected. If your datasets have duplicate nodes you could see spurious results.
- Across domains (and processors) we use a Node-In-Cell intersection test to determine connectivity. If any node of a cell evaluates "inside" of another cell, they are connected.

This intersection test is efficient and covers our current use cases, however there are cases that may require Edge-Face intersection tests, For example:

We do not currently provide Edge-Face intersection capability but if your data requires this and you have an example dataset please contact the VisIt team and we will be happy to investigate this option.