Using the Tree and PtTree classes

For more advanced usage and additional features, please refer to the class API in tree.hpp.

1. Overview of Tree and PtTree Classes

Tree Class:
- Represents a generic distributed/parallel tree data structure.
- Provides functionalities for tree manipulation, refinement, data addition, retrieval, and visualization.
- Designed to handle tree structures in arbitrary dimensions.
PtTree Class:
- Inherits from the Tree class and specializes in handling point data within the tree structure.
- Specifically designed for scenarios where points are distributed across multiple processors.
- Provides additional functionalities for adding, retrieving, and visualizing point data.

2. Usage of Tree Class

To use the Tree class, follow these steps:

Initialization:
```
Tree<Real, DIM> tree;
```
Create an instance of the Tree class. Optionally, you can specify the datatype Real and the dimensionality DIM.
Adding Data:
```
Vector<Real> data;
Vector<Long> cnt;
tree.AddData("name", data, cnt);
```
Add data to the tree nodes. Provide a name for the data, along with the corresponding data vector and count vector.

Data Retrieval:

Vector<Real> retrievedData;
Vector<Long> counts;
tree.GetData(retrievedData, counts, "name");

Retrieve data from the tree nodes using the specified data name.

Visualization:
```
tree.WriteTreeVTK("tree");
```
Generate a VTK visualization of the tree structure.

3. Usage of PtTree Class

To utilize the PtTree class for point data management, follow these steps:

Initialization:
```
PtTree<Real, DIM> ptTree;
```
Create an instance of the PtTree class, which inherits from the Tree class.
Adding Particles:
```
Vector<Real> coordinates;
ptTree.AddParticles("pt", coordinates);
```
Add particle coordinates to the point tree, specifying a name for the particle group.
Adding Particle Data:
```
Vector<Real> particleData;
ptTree.AddParticleData("data_name", "pt", particleData);
```
Add data associated with the particles. Provide a name for the data, along with the corresponding particle group name.
Update Refinement:
```
ptTree.UpdateRefinement(coordinates, 1000);
```
Update the refinement of the point tree based on the given coordinates, with a maximum number of points per box.

4. Example: Tree and PtTree in Action

Here’s an example demonstrating the usage of the PtTree class:

template <class Real, Integer DIM> void ExamplePtTree() {
    Long N = 100000;
    Vector<Real> X(N*DIM), f(N);
    for (Long i = 0; i < N; i++) { // Set coordinates (X), and values (f)
      f[i] = 0;
      for (Integer k = 0; k < DIM; k++) {
        X[i*DIM+k] = pow<3>(drand48()*2-1.0)*0.5+0.5;
        f[i] += X[i*DIM+k]*k;
      }
    }

    PtTree<Real,DIM> tree;
    tree.AddParticles("pt", X);
    tree.AddParticleData("pt-value", "pt", f);
    tree.UpdateRefinement(X, 1000); // refine tree with max 1000 points per box.

    { // manipulate tree node data
      const auto& node_lst = tree.GetNodeLists(); // Get interaction lists
      //const auto& node_mid = tree.GetNodeMID();
      //const auto& node_attr = tree.GetNodeAttr();

      // get point values and count for each node
      Vector<Real> value;
      Vector<Long> cnt, dsp;
      tree.GetData(value, cnt, "pt-value");

      // compute the dsp (the point offset) for each node
      dsp.ReInit(cnt.Dim()); dsp = 0;
      omp_par::scan(cnt.begin(), dsp.begin(), cnt.Dim());

      Long node_idx = 0;
      for (Long i = 0; i < cnt.Dim(); i++) { // find the tree node with maximum points
        if (cnt[node_idx] < cnt[i]) node_idx = i;
      }

      for (Long j = 0; j < cnt[node_idx]; j++) { // for this node, set all pt-value to -1
        value[dsp[node_idx]+j] = -1;
      }

      for (const Long nbr_idx : node_lst[node_idx].nbr) { // loop over the neighbors and set pt-value to 2
        if (nbr_idx >= 0 && nbr_idx != node_idx) {
          for (Long j = 0; j < cnt[nbr_idx]; j++) {
            value[dsp[nbr_idx]+j] = 2;
          }
        }
      }
    }

    // Generate visualization
    tree.WriteParticleVTK("pt", "pt-value");
    tree.WriteTreeVTK("tree");
}

This example initializes a point tree, adds particles with associated values, updates the refinement of the tree, manipulates node data, and generates visualization outputs.