ExaFMM-T

https://exafmm.github.io/exafmm-t/
Admin
ExaFMM-T is an open-source fast multipole method library for simulating N-body interactions with...
Tokens:156,370
Snippets:518
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Function: exafmm_t::start

Source: https://exafmm.github.io/exafmm-t/_sources/api/function_namespaceexafmm__t_1a86c1b2909c9ba1c73e680684fd98bf82.rst.txt

Documentation for the start function defined in include/timer.h.

```APIDOC
## Function exafmm_t::start

### Description
Starts a timer associated with the provided string identifier.

### Parameters
- **name** (std::string) - Required - The identifier for the timer to start.
```

--------------------------------

### Install Dependencies on Ubuntu

Source: https://exafmm.github.io/exafmm-t/_sources/compile.rst.txt

Installs essential libraries for exafmm-t on Ubuntu systems. Ensure your system is updated before running.

```bash
$ apt-get update
$ apt-get -y install libopenblas-dev libfftw3-dev gfortran
```

--------------------------------

### Install exafmm-t Headers

Source: https://exafmm.github.io/exafmm-t/_sources/compile.rst.txt

Installs the exafmm-t headers to the configured location. This is an optional step for C++ users.

```bash
make install
```

--------------------------------

### Install Dependencies on Ubuntu

Source: https://exafmm.github.io/exafmm-t/compile.html

Installs essential libraries like OpenBLAS, FFTW3, and GFortran required for exafmm-t. Ensure your system is updated before running.

```bash
$ apt-get update
$ apt-get -y install libopenblas-dev libfftw3-dev gfortran

```

--------------------------------

### void exafmm_t::start(std::string event)

Source: https://exafmm.github.io/exafmm-t/api/function_namespaceexafmm__t_1a86c1b2909c9ba1c73e680684fd98bf82.html

Starts a timer event identified by the provided string name.

```APIDOC
## void exafmm_t::start(std::string event)

### Description
Starts a timer event. This function is defined in timer.h and is used to begin tracking the duration of a specific operation.

### Parameters
#### Request Body
- **event** (std::string) - Required - The name of the event to start timing.
```

--------------------------------

### Install exafmm-t Python Package

Source: https://exafmm.github.io/exafmm-t/compile.html

Installs the exafmm-t Python package using pip from a GitHub repository. This method requires OpenBLAS to be installed beforehand.

```bash
pip install git+https://github.com/exafmm/exafmm-t.git

```

--------------------------------

### Initialize FMM Operators

Source: https://exafmm.github.io/exafmm-t/_sources/examples.rst.txt

Prepare relative coordinates, colleague nodes, and M2L setup.

```cpp
exafmm_t::init_rel_coord();        // compute all possible relative positions of nodes for each FMM operator
exafmm_t::set_colleagues(nodes);   // find colleague nodes
exafmm_t::build_list(nodes, fmm);  // create list for each FMM operator
fmm.M2L_setup(nonleafs);           // an extra setup for M2L operator
```

--------------------------------

### Install exafmm-t Python Package

Source: https://exafmm.github.io/exafmm-t/_sources/compile.rst.txt

Installs the exafmm-t Python package using pip. Ensure OpenBLAS and other dependencies are installed prior to this step.

```bash
pip install git+https://github.com/exafmm/exafmm-t.git
```

--------------------------------

### Precompute M2L Matrices (Complex)

Source: https://exafmm.github.io/exafmm-t/api/program_listing_file_include_fmm.h.html

Initializes structures and creates an FFT plan for precomputing Multipole-to-Local (M2L) matrices when using complex number types. This is the setup phase before the main computation.

```cpp
  template <>
  void Fmm<complex_t>::precompute_M2L(std::ofstream& file) {
    int n1 = this->p * 2;
    int& nconv_ = this->nconv;
    int& nfreq_ = this->nfreq;
    int fft_size = 2 * nfreq_ * NCHILD * NCHILD;
    std::vector<RealVec> matrix_M2L_Helper(REL_COORD[M2L_Helper_Type].size(),
                                           RealVec(2*nfreq_));
    std::vector<AlignedVec> matrix_M2L(REL_COORD[M2L_Type].size(), AlignedVec(fft_size));
    // create fft plan
    RealVec fftw_in(nconv_);
    RealVec fftw_out(2*nfreq_);
    int dim[3] = {n1, n1, n1};
    fft_plan plan = fft_plan_dft(3, dim,
                                 reinterpret_cast<fft_complex*>(fftw_in.data()),
                                 reinterpret_cast<fft_complex*>(fftw_out.data()),

```

--------------------------------

### M2L Interaction Setup

Source: https://exafmm.github.io/exafmm-t/api/program_listing_file_include_fmm_scale_invariant.h.html

Constructs source and target node lists and calculates interaction offsets for the Multipole-to-Local (M2L) operator.

```cpp
    void M2L_setup(NodePtrs<T> nonleafs) {
      int& nsurf_ = this->nsurf;
      int npos = REL_COORD[M2L_Type].size();  // number of M2L relative positions

      // construct lists of source nodes and target nodes for M2L operator
      NodePtrs<T>& trg_nodes = nonleafs;
      std::set<Node<T>*> src_nodes_;
      for (size_t i=0; i<trg_nodes.size(); i++) {
        NodePtrs<T>& M2L_list = trg_nodes[i]->M2L_list;
        for (int k=0; k<npos; k++) {
          if (M2L_list[k]) {
            src_nodes_.insert(M2L_list[k]);
          }
        }
      }
      NodePtrs<T> src_nodes;
      auto it = src_nodes_.begin();
      for (; it!=src_nodes_.end(); it++) {
        src_nodes.push_back(*it);
      }

      // prepare the indices of src_nodes & trg_nodes in all_up_equiv & all_dn_equiv
      std::vector<size_t> fft_offset(src_nodes.size());
      std::vector<size_t> ifft_offset(trg_nodes.size());
      RealVec ifft_scale(trg_nodes.size());
      for (size_t i=0; i<src_nodes.size(); i++) {
        fft_offset[i] = src_nodes[i]->children[0]->idx * nsurf_;
      }
      for (size_t i=0; i<trg_nodes.size(); i++) {
        int level = trg_nodes[i]->level+1;
        ifft_offset[i] = trg_nodes[i]->children[0]->idx * nsurf_;
        ifft_scale[i] = powf(2.0, level);
      }

      // calculate interaction_offset_f & interaction_count_offset
      std::vector<size_t> interaction_offset_f;
      std::vector<size_t> interaction_count_offset;
      for (size_t i=0; i<src_nodes.size(); i++) {
        src_nodes[i]->idx_M2L = i;
      }
      size_t nblk_trg = trg_nodes.size() * sizeof(real_t) / CACHE_SIZE;
      if (nblk_trg==0) nblk_trg = 1;
      size_t interaction_count_offset_ = 0;
      size_t fft_size = 2 * NCHILD * this->nfreq;
      for (size_t iblk_trg=0; iblk_trg<nblk_trg; iblk_trg++) {
        size_t blk_start = (trg_nodes.size()* iblk_trg   ) / nblk_trg;
        size_t blk_end   = (trg_nodes.size()*(iblk_trg+1)) / nblk_trg;
        for (int k=0; k<npos; k++) {
          for (size_t i=blk_start; i<blk_end; i++) {
            NodePtrs<T>& M2L_list = trg_nodes[i]->M2L_list;
            if (M2L_list[k]) {
              interaction_offset_f.push_back(M2L_list[k]->idx_M2L * fft_size);
              interaction_offset_f.push_back(        i           * fft_size);
              interaction_count_offset_++;
            }
          }
          interaction_count_offset.push_back(interaction_count_offset_);
        }
      }
      m2ldata.fft_offset = fft_offset;
      m2ldata.ifft_offset = ifft_offset;
      m2ldata.ifft_scale = ifft_scale;
      m2ldata.interaction_offset_f = interaction_offset_f;
      m2ldata.interaction_count_offset = interaction_count_offset;
    }
```

--------------------------------

### M2L Setup and Data Preparation in ExaFMM

Source: https://exafmm.github.io/exafmm-t/api/program_listing_file_include_fmm.h.html

This function sets up data structures for the M2L (Multipole-to-Local) operator. It constructs lists of target nodes and prepares interaction offsets for efficient M2L calculations across different levels of the octree.

```cpp
void M2L_setup(NodePtrs<T>& nonleafs) {
      int& nsurf_ = this->nsurf;
      int& depth_ = this->depth;
      int npos = REL_COORD[M2L_Type].size();  // number of M2L relative positions
      m2ldata.resize(depth_);                  // initialize m2ldata

      // construct lists of target nodes for M2L operator at each level
      std::vector<NodePtrs<T>> trg_nodes(depth_);
      for (size_t i=0; i<nonleafs.size(); i++) {
        trg_nodes[nonleafs[i]->level].push_back(nonleafs[i]);
      }

      // prepare for m2ldata for each level
      for (int l=0; l<depth_; l++) {
        // construct M2L source nodes for current level
        std::set<Node<T>*> src_nodes_;
        for (size_t i=0; i<trg_nodes[l].size(); i++) {
          NodePtrs<T>& M2L_list = trg_nodes[l][i]->M2L_list;
          for (int k=0; k<npos; k++) {
            if (M2L_list[k])
              src_nodes_.insert(M2L_list[k]);
          }
        }
        NodePtrs<T> src_nodes;
        auto it = src_nodes_.begin();
        for (; it!=src_nodes_.end(); it++) {
          src_nodes.push_back(*it);
        }
        // prepare the indices of src_nodes & trg_nodes in all_up_equiv & all_dn_equiv
        std::vector<size_t> fft_offset(src_nodes.size());       // displacement in all_up_equiv
        std::vector<size_t> ifft_offset(trg_nodes[l].size());  // displacement in all_dn_equiv
        for (size_t i=0; i<src_nodes.size(); i++) {
          fft_offset[i] = src_nodes[i]->children[0]->idx * nsurf_;
        }
        for (size_t i=0; i<trg_nodes[l].size(); i++) {
          ifft_offset[i] = trg_nodes[l][i]->children[0]->idx * nsurf_;
        }

        // calculate interaction_offset_f & interaction_count_offset
        std::vector<size_t> interaction_offset_f;
        std::vector<size_t> interaction_count_offset;
        for (size_t i=0; i<src_nodes.size(); i++) {
          src_nodes[i]->idx_M2L = i;  // node_id: node's index in src_nodes list
        }
        size_t nblk_trg = trg_nodes[l].size() * sizeof(real_t) / CACHE_SIZE;
        if (nblk_trg==0) nblk_trg = 1;
        size_t interaction_count_offset_ = 0;
        size_t fft_size = 2 * NCHILD * this->nfreq;
        for (size_t iblk_trg=0; iblk_trg<nblk_trg; iblk_trg++) {
          size_t blk_start = (trg_nodes[l].size()* iblk_trg   ) / nblk_trg;
          size_t blk_end   = (trg_nodes[l].size()*(iblk_trg+1)) / nblk_trg;
          for (int k=0; k<npos; k++) {
            for (size_t i=blk_start; i<blk_end; i++) {
              NodePtrs<T>& M2L_list = trg_nodes[l][i]->M2L_list;
              if (M2L_list[k]) {
                interaction_offset_f.push_back(M2L_list[k]->idx_M2L * fft_size);   // src_node's displacement in fft_in
                interaction_offset_f.push_back(        i           * fft_size);   // trg_node's displacement in fft_out
                interaction_count_offset_++;
              }
            }
            interaction_count_offset.push_back(interaction_count_offset_);
          }
        }
        m2ldata[l].fft_offset = fft_offset;
        m2ldata[l].ifft_offset = ifft_offset;
        m2ldata[l].interaction_offset_f = interaction_offset_f;
        m2ldata[l].interaction_count_offset = interaction_count_offset;
      }
    }

```

--------------------------------

### FMM Tree List Construction and Colleague Setup

Source: https://exafmm.github.io/exafmm-t/_sources/api/program_listing_file_include_build_list.h.rst.txt

Contains template functions for building interaction lists across different tree levels and setting up node colleagues for FMM operations.

```cpp
#ifndef build_list_h
#define build_list_h
#include "exafmm_t.h"
#include "geometry.h"
#include "fmm_base.h"

namespace exafmm_t {
  template <typename T>
  void build_list_parent_level(Node<T>* n, const FmmBase<T>& fmm) {
    if (!n->parent) return;
    ivec3 rel_coord;
    int octant = n->octant;
    bool isleaf = n->is_leaf;
    for (int i=0; i<27; i++) {
      Node<T> * pc = n->parent->colleagues[i];
      if (pc && pc->is_leaf) {
        rel_coord[0] = ( i %3)*4-4-(octant & 1?2:0)+1;
        rel_coord[1] = ((i/3)%3)*4-4-(octant & 2?2:0)+1;
        rel_coord[2] = ((i/9)%3)*4-4-(octant & 4?2:0)+1;
        int c_hash = hash(rel_coord);
        if (isleaf) {
          int idx1 = HASH_LUT[P2P0_Type][c_hash];
          if (idx1>=0)
            n->P2P_list.push_back(pc);
        }
        int idx2 = HASH_LUT[P2L_Type][c_hash];
        if (idx2>=0) {
          if (isleaf && n->ntrgs<=fmm.nsurf)
            n->P2P_list.push_back(pc);
          else
            n->P2L_list.push_back(pc);
        }
      }
    }
  }

  template <typename T>
  void build_list_current_level(Node<T>* n) {
    ivec3 rel_coord;
    bool isleaf = n->is_leaf;
    for (int i=0; i<27; i++) {
      Node<T> * col = n->colleagues[i];
      if(col) {
        rel_coord[0] = ( i %3)-1;
        rel_coord[1] = ((i/3)%3)-1;
        rel_coord[2] = ((i/9)%3)-1;
        int c_hash = hash(rel_coord);
        if (col->is_leaf && isleaf) {
          int idx1 = HASH_LUT[P2P1_Type][c_hash];
          if (idx1>=0)
            n->P2P_list.push_back(col);
        } else if (!col->is_leaf && !isleaf) {
          int idx2 = HASH_LUT[M2L_Type][c_hash];
          if (idx2>=0)
            n->M2L_list[idx2] = col;
        }
      }
    }
  }
  
  template <typename T>
  void build_list_child_level(Node<T>* n, const FmmBase<T>& fmm) {
    if (!n->is_leaf) return;
    ivec3 rel_coord;
    for(int i=0; i<27; i++) {
      Node<T>* col = n->colleagues[i];
      if(col && !col->is_leaf) {
        for(int j=0; j<NCHILD; j++) {
          Node<T>* cc = col->children[j];
          rel_coord[0] = ( i %3)*4-4+(j & 1?2:0)-1;
          rel_coord[1] = ((i/3)%3)*4-4+(j & 2?2:0)-1;
          rel_coord[2] = ((i/9)%3)*4-4+(j & 4?2:0)-1;
          int c_hash = hash(rel_coord);
          int idx1 = HASH_LUT[P2P2_Type][c_hash];
          int idx2 = HASH_LUT[M2P_Type][c_hash];
          if (idx1>=0) {
            assert(col->children[j]->is_leaf); //2:1 balanced
            n->P2P_list.push_back(cc);
          }
          // since we currently don't save bodies' information in nonleaf nodes
          // M2P can only be switched to P2P when source is leaf
          if (idx2>=0) {
            if (cc->is_leaf && cc->nsrcs<=fmm.nsurf)
              n->P2P_list.push_back(cc);
            else
              n->M2P_list.push_back(cc);
          }
        }
      }
    }
  }

  template <typename T>
  void build_list(Nodes<T>& nodes, const FmmBase<T>& fmm) {
    #pragma omp parallel for
    for(size_t i=0; i<nodes.size(); i++) {
      Node<T>* node = &nodes[i];
      node->M2L_list.resize(REL_COORD[M2L_Type].size(), nullptr);
      build_list_parent_level(node, fmm);   // P2P0 & P2L
      build_list_current_level(node);  // P2P1 & M2L
#if NON_ADAPTIVE
      if (node->ntrgs)
        build_list_child_level(node, fmm);  // P2P2 & M2P
#else
      build_list_child_level(node, fmm);    // P2P2 & M2P
#endif
    }
  }

  template <typename T>
  void set_colleagues(Node<T>* node) {
    Node<T> *parent, *colleague, *child;
    node->colleagues.resize(27, nullptr);
    if (node->level==0) {     // root node
      node->colleagues[13] = node;
    } else {                  // non-root node
      parent = node->parent;
      int l = node->octant;
      for (int i=0; i<27; ++i) { // loop over parent's colleagues
        colleague = parent->colleagues[i]; 
        if (colleague && !colleague->is_leaf) {
          for (int j=0; j<8; ++j) {  // loop over parent's colleages child
            child = colleague->children[j];
            if (child) {
              bool flag = true;
              int a = 1;
              int b = 1;
              int new_idx = 0;
              for (int k=0; k<3; ++k) {
                int idx_diff = (((i/b)%3)-1)*2 + ((j/a)%2) - ((l/a)%2);
```

--------------------------------

### Build HTML Documentation

Source: https://exafmm.github.io/exafmm-t/_sources/documentation.rst.txt

Navigate to the docs directory and run make html to generate the HTML documentation. The output will be located in the docs/_build/html directory.

```bash
$ cd docs
$ make html
```

--------------------------------

### Initialize Tree Construction

Source: https://exafmm.github.io/exafmm-t/_sources/api/program_listing_file_include_build_tree.h.rst.txt

Entry point for building the tree, initializing the root node and buffers.

```cpp
template <typename T>
     Nodes<T> build_tree(Bodies<T>& sources, Bodies<T>& targets,
                         NodePtrs<T>& leafs, NodePtrs<T>& nonleafs,
                         FmmBase<T>& fmm, const Keys& leafkeys=Keys()) {
       Bodies<T> sources_buffer = sources;
       Bodies<T> targets_buffer = targets;
       Nodes<T> nodes(1);
       nodes[0].parent = nullptr;
       nodes[0].octant = 0;
       nodes[0].x = fmm.x0;
       nodes[0].r = fmm.r0;
       nodes[0].level = 0;
       nodes.reserve((sources.size()+targets.size()) * (32/fmm.ncrit+1));
       build_tree(&sources[0], &sources_buffer[0], 0, sources.size(), 
                  &targets[0], &targets_buffer[0], 0, targets.size(),
                  &nodes[0], nodes, leafs, nonleafs,
                  leafkeys, fmm);
       return nodes;
     }
```

--------------------------------

### Initialize Sources and Targets in C++

Source: https://exafmm.github.io/exafmm-t/_sources/examples.rst.txt

Create random particle distributions for sources and targets using STL vectors.

```cpp
using exafmm_t::real_t;
std::random_device rd;
std::mt19937 gen(rd());  // random number generator
std::uniform_real_distribution<> dist(-1.0, 1.0);
int ntargets = 100000;
int nsources = 100000;

exafmm_t::Bodies<real_t> sources(nsources);
for (int i=0; i<nsources; i++) {
  sources[i].ibody = i;
  sources[i].q = dist(gen);        // charge
  for (int d=0; d<3; d++)
    sources[i].X[d] = dist(gen);   // location
}

exafmm_t::Bodies<real_t> targets(ntargets);
for (int i=0; i<ntargets; i++) {
  targets[i].ibody = i;
  for (int d=0; d<3; d++)
    targets[i].X[d] = dist(gen);   // location
}
```

--------------------------------

### Tree Initialization

Source: https://exafmm.github.io/exafmm-t/_sources/api/program_listing_file_include_build_non_adaptive_tree.h.rst.txt

Initializes the root node and reserves memory for the tree structure before starting the recursive build process.

```cpp
template <typename T>
     Nodes<T> build_tree(Bodies<T>& sources, Bodies<T>& targets,
                         NodePtrs<T>& leafs, NodePtrs<T>& nonleafs, FmmBase<T>& fmm) {
       Nodes<T> nodes(1);
       nodes[0].parent = nullptr;
       nodes[0].octant = 0;
       nodes[0].x = fmm.x0;
       nodes[0].r = fmm.r0;
       nodes[0].level = 0;
       nodes.reserve((pow(8, fmm.depth+1)-1) / 7);  // reserve for 8^(level+1)/7 nodes
       build_tree(&sources[0], 0, sources.size(),
                  &targets[0], 0, targets.size(),
                  &nodes[0], nodes, leafs, nonleafs, fmm);
       return nodes;
     }
   }
   #endif
```

--------------------------------

### Function: exafmm_t::init_sources

Source: https://exafmm.github.io/exafmm-t/_sources/api/function_namespaceexafmm__t_1ad0528ffe62eca34477475f058ef3b075.rst.txt

Initializes sources for the ExaFMM-t simulation environment.

```APIDOC
## Function: exafmm_t::init_sources(int, const char *, int)

### Description
Initializes the data sources required for the simulation. Defined in file_include_dataset.h.

### Parameters
- **arg1** (int) - Required - First integer parameter for initialization.
- **arg2** (const char *) - Required - Character pointer parameter for initialization.
- **arg3** (int) - Required - Second integer parameter for initialization.
```

--------------------------------

### build_list.h Overview

Source: https://exafmm.github.io/exafmm-t/_sources/api/file_include_build_list.h.rst.txt

Overview of the build_list.h header file, including dependencies and function references.

```APIDOC
## File: include/build_list.h

### Description
This header file defines core functionality for building lists within the ExaFMM framework.

### Includes
- exafmm_t.h
- fmm_base.h
- geometry.h

### Namespace
- exafmm_t

### Functions
- exhale_function_namespaceexafmm__t_1a36c77b3d59826372f25bc4d637a9ee6b
- exhale_function_namespaceexafmm__t_1aa95f7cdc9f863143b78c8b85d7580adf
- exhale_function_namespaceexafmm__t_1a4072daf9d26f03648eb5007a74cddda8
- exhale_function_namespaceexafmm__t_1a4c5585ab36a873853bd1037a305174ff
- exhale_function_namespaceexafmm__t_1a7e01b7c369f769d9eb64c49d0523bb5e
- exhale_function_namespaceexafmm__t_1a99a87ebc089fc38be60f0ba46a256485
```

--------------------------------

### Set Colleagues for All Nodes (C++)

Source: https://exafmm.github.io/exafmm-t/api/program_listing_file_include_build_list.h.html

Initializes the 'colleagues' pointers for all nodes in a given list by calling the single-node version starting from the root.

```cpp
  template <typename T>
  void set_colleagues(Nodes<T>& nodes) {
    set_colleagues(&nodes[0]);
  }
```

--------------------------------

### build_tree.h - File Overview

Source: https://exafmm.github.io/exafmm-t/api/file_include_build_tree.h.html

Provides an overview of the build_tree.h file, including its definition, includes, namespaces, and functions.

```APIDOC
## File build_tree.h

### Description
This file contains functions related to building and manipulating tree structures within the ExaFMM-T library.

### Includes
- cassert
- exafmm_t.h
- fmm_base.h
- hilbert.h
- queue
- unordered_map

### Namespaces
- Namespace exafmm_t

### Functions
- Template Function exafmm_t::balance_tree(const Keys&, const std::unordered_map<uint64_t, size_t>&, const Nodes<K>&)
- Template Function exafmm_t::balance_tree(Nodes<T>&, Bodies<T>&, Bodies<T>&, NodePtrs<T>&, NodePtrs<T>&, FmmBase<T>&)
- Template Function exafmm_t::breadth_first_traversal
- Template Function exafmm_t::build_tree(Body<T> *, Body<T> *, int, int, Body<T> *, Body<T> *, int, int, Node<T> *, Nodes<T>&, NodePtrs<T>&, NodePtrs<T>&, const Keys&, FmmBase<T>&, bool)
- Template Function exafmm_t::build_tree(Bodies<T>&, Bodies<T>&, NodePtrs<T>&, NodePtrs<T>&, FmmBase<T>&, const Keys&)
- Function exafmm_t::find_leaf_keys
- Template Function exafmm_t::sort_bodies(Node<T> *const, Body<T> *const, Body<T> *const, int, int, std::vector<int>&, std::vector<int>&)
```

--------------------------------

### Initialize Relative Coordinates and M2L Index Map

Source: https://exafmm.github.io/exafmm-t/api/program_listing_file_include_geometry.h.html

Initializes relative coordinates for M2L and M2P types, and generates the M2L index map. This is typically called once during setup.

```cpp
init_rel_coord(1, 1, 1, M2L_Type);
init_rel_coord(5, 5, 2, M2P_Type);
init_rel_coord(5, 5, 2, P2L_Type);
generate_M2L_index_map();
is_initialized = true;
```

--------------------------------

### Function: exafmm_t::init_sources

Source: https://exafmm.github.io/exafmm-t/_sources/api/function_namespaceexafmm__t_1ad41a7b3f40be1d43245d44b63be08743.rst.txt

Documentation for the init_sources function used to initialize sources in the ExaFMM-t library.

```APIDOC
## Function exafmm_t::init_sources(int, const char *, int)

### Description
Initializes sources for the ExaFMM-t simulation environment.

### Parameters
- **arg1** (int) - Required - First integer parameter for initialization.
- **arg2** (const char *) - Required - Character pointer parameter for initialization.
- **arg3** (int) - Required - Second integer parameter for initialization.

### Defined in
file_include_dataset.h
```

--------------------------------

### File Overview: include/args.h

Source: https://exafmm.github.io/exafmm-t/_sources/api/file_include_args.h.rst.txt

Technical overview of the args.h header file, including its dependencies and class definitions.

```APIDOC
## File: include/args.h

### Description
This header file defines the command-line argument parsing structure for the ExaFMM-t project.

### Dependencies
- cstdio
- cstdlib
- getopt.h
- iomanip
- iostream
- omp.h

### Namespaces
- exafmm_t

### Classes
- exafmm_t::Args

### Included By
- include/exafmm_t.h
```

--------------------------------

### Real IFFT for DN Equivalents (Exafmm)

Source: https://exafmm.github.io/exafmm-t/api/program_listing_file_include_fmm.h.html

Performs a complex-to-real inverse FFT for DN equivalents using FFTW. This function is specialized for `real_t` and requires setup with `fft_plan_many_dft_c2r`. Ensure correct data alignment and buffer sizes.

```cpp
template <>
    void Fmm<real_t>::ifft_dn_check(std::vector<size_t>& ifft_offset, AlignedVec& fft_out, RealVec& all_dn_equiv) {
    int& nsurf_ = this->nsurf;
    int& nconv_ = this->nconv;
    int& nfreq_ = this->nfreq;
    int n1 = this->p * 2;
    auto map = generate_surf2conv_dn(p);

    size_t fft_size = 2 * NCHILD * nfreq_;
    AlignedVec fftw_in(fft_size);
    AlignedVec fftw_out(nconv_ * NCHILD);
    int dim[3] = {n1, n1, n1};

    fft_plan plan = fft_plan_many_dft_c2r(3, dim, NCHILD,
                    (fft_complex*)(&fftw_in[0]), nullptr, 1, nfreq_,
                    (real_t*)(&fftw_out[0]), nullptr, 1, nconv_,
                    FFTW_ESTIMATE);

#pragma omp parallel for
    for (size_t node_idx=0; node_idx<ifft_offset.size(); node_idx++) {
      RealVec buffer0(fft_size, 0);
      RealVec buffer1(fft_size, 0);
      real_t* dn_check_f = &fft_out[fft_size*node_idx];  // offset ptr for node_idx in fft_out vector, size=fftsize
      real_t* dn_equiv = &all_dn_equiv[ifft_offset[node_idx]];  // offset ptr for node_idx's child's dn_equiv in all_dn_equiv, size=numChilds * nsurf_ 
      for (int k=0; k<nfreq_; k++)
        for (int j=0; j<NCHILD; j++) {
          buffer0[2*(nfreq_*j+k)+0] = dn_check_f[2*(NCHILD*k+j)+0];
          buffer0[2*(nfreq_*j+k)+1] = dn_check_f[2*(NCHILD*k+j)+1];
        }
      fft_execute_dft_c2r(plan, (fft_complex*)&buffer0[0], (real_t*)(&buffer1[0]));
      for (int k=0; k<nsurf_; k++) {
        size_t idx = map[k];
        for (int j=0; j<NCHILD; j++)
          dn_equiv[nsurf_*j+k] += buffer1[idx+j*nconv_];
      }
    }
    fft_destroy_plan(plan);
  }
```

--------------------------------

### Initialize and Build Octree

Source: https://exafmm.github.io/exafmm-t/api/program_listing_file_include_build_tree.h.html

Initializes the root node and calls the recursive build_tree function to construct the entire octree. Reserves space for nodes based on input sizes.

```cpp
template <typename T>
  Nodes<T> build_tree(Bodies<T>& sources, Bodies<T>& targets,
                      NodePtrs<T>& leafs, NodePtrs<T>& nonleafs,
                      FmmBase<T>& fmm, const Keys& leafkeys=Keys()) {
    Bodies<T> sources_buffer = sources;
    Bodies<T> targets_buffer = targets;
    Nodes<T> nodes(1);
    nodes[0].parent = nullptr;
    nodes[0].octant = 0;
    nodes[0].x = fmm.x0;
    nodes[0].r = fmm.r0;
    nodes[0].level = 0;
    nodes.reserve((sources.size()+targets.size()) * (32/fmm.ncrit+1));
    build_tree(&sources[0], &sources_buffer[0], 0, sources.size(),
               &targets[0], &targets_buffer[0], 0, targets.size(),
               &nodes[0], nodes, leafs, nonleafs,
               leafkeys, fmm);
    return nodes;
  }
```

--------------------------------

### Initialize Sources with Random Charge

Source: https://exafmm.github.io/exafmm-t/api/program_listing_file_include_dataset.h.html

Initializes source bodies using a specified distribution and seed, then assigns a random charge (q) between -0.5 and 0.5.

```cpp
  template <typename T>
  Bodies<T> init_sources(int numBodies, const char* distribution, int seed) {
    Bodies<T> bodies = init_targets<T>(numBodies, distribution, seed);
    for (int b=0; b<numBodies; ++b) {
      bodies[b].q = drand48() - 0.5;
    }
    return bodies;
  }

```

--------------------------------

### Class exafmm_t::Args

Source: https://exafmm.github.io/exafmm-t/api/classexafmm__t_1_1Args.html

Documentation for the Args class constructor and public members used for simulation configuration.

```APIDOC
## Class exafmm_t::Args

### Description
Represents the configuration arguments for the ExaFMM simulation, defined in args.h.

### Public Functions
- **Args(int argc = 0, char **argv = nullptr)** - Constructor that initializes arguments from command-line inputs.
- **void print(int stringLength = 20)** - Prints the current configuration parameters to standard output.

### Public Members
- **ncrit** (int) - Critical number of bodies per leaf node.
- **distribution** (const char*) - Type of particle distribution.
- **k** (double) - Wave number.
- **maxlevel** (int) - Maximum depth of the octree.
- **numBodies** (int) - Total number of bodies in the simulation.
- **P** (int) - Order of the multipole expansion.
- **threads** (int) - Number of threads to use for execution.
```

--------------------------------

### Compile and Test exafmm-t

Source: https://exafmm.github.io/exafmm-t/_sources/compile.rst.txt

Compiles the exafmm-t library and runs its tests. Execute these commands from the root directory of the repository after configuration.

```bash
make check
```

--------------------------------

### Hilbert and 3D Indexing Utilities in C++

Source: https://exafmm.github.io/exafmm-t/_sources/api/program_listing_file_include_hilbert.h.rst.txt

Provides functions for octree level management, Hilbert key generation, and coordinate mapping. Requires exafmm_t.h and standard C++ headers.

```cpp
#ifndef hilbert_h
#define hilbert_h
#include <cstdlib>
#include <stdint.h>
#include "exafmm_t.h"
#define EXAFMM_HILBERT 0 

namespace exafmm_t {
  inline uint64_t levelOffset(int level) {
    return (((uint64_t)1 << 3 * level) - 1) / 7;
  }

  int getLevel(uint64_t i) {
    int level = -1;
    uint64_t offset = 0;
    while (i >= offset) {
      level++;
      offset += (uint64_t)1 << 3 * level;
    }
    return level;
  }

  uint64_t getParent(uint64_t i) {
    int level = getLevel(i);
    return (i - levelOffset(level)) / 8 + levelOffset(level-1);
  }

  uint64_t getChild(uint64_t i) {
    int level = getLevel(i);
    return (i - levelOffset(level)) * 8 + levelOffset(level+1);
  }
  
  int getOctant(uint64_t key, bool offset=true) {
    int level = getLevel(key);
    if (offset) key -= levelOffset(level);
    return key & 7;
  }

  uint64_t getKey(ivec3 iX, int level, bool offset=true) {
#if EXAFMM_HILBERT
    int M = 1 << (level - 1);
    for (int Q=M; Q>1; Q>>=1) {
      int R = Q - 1;
      for (int d=0; d<3; d++) {
        if (iX[d] & Q) iX[0] ^= R;
        else {
          int t = (iX[0] ^ iX[d]) & R;
          iX[0] ^= t;
          iX[d] ^= t;
        }
      }
    }
    for (int d=1; d<3; d++) iX[d] ^= iX[d-1];
    int t = 0;
    for (int Q=M; Q>1; Q>>=1)
      if (iX[2] & Q) t ^= Q - 1;
    for (int d=0; d<3; d++) iX[d] ^= t;
#endif
    uint64_t i = 0;
    for (int l=0; l<level; l++) {
      i |= (iX[2] & (uint64_t)1 << l) << 2*l;
      i |= (iX[1] & (uint64_t)1 << l) << (2*l + 1);
      i |= (iX[0] & (uint64_t)1 << l) << (2*l + 2);
    }
    if (offset) i += levelOffset(level);
    return i;
  }

  ivec3 get3DIndex(uint64_t i) {
    int level = getLevel(i);
    i -= levelOffset(level);
    ivec3 iX = 0;
    for (int l=0; l<level; l++) {
      iX[2] |= (i & (uint64_t)1 << 3*l) >> 2*l;
      iX[1] |= (i & (uint64_t)1 << (3*l + 1)) >> (2*l + 1);
      iX[0] |= (i & (uint64_t)1 << (3*l + 2)) >> (2*l + 2);
    }
#if EXAFMM_HILBERT
    int N = 2 << (level - 1);
    int t = iX[2] >> 1;
    for (int d=2; d>0; d--) iX[d] ^= iX[d-1];
    iX[0] ^= t;
    for (int Q=2; Q!=N; Q<<=1) {
      int R = Q - 1;
      for (int d=2; d>=0; d--) {
        if (iX[d] & Q) iX[0] ^= R;
        else {
          t = (iX[0] ^ iX[d]) & R;
          iX[0] ^= t;
          iX[d] ^= t;
        }
      }
    }
#endif
    return iX;
  }

  ivec3 get3DIndex(uint64_t i, int level) {
    ivec3 iX = 0;
    for (int l=0; l<level; l++) {
      iX[2] |= (i & (uint64_t)1 << 3*l) >> 2*l;
      iX[1] |= (i & (uint64_t)1 << (3*l + 1)) >> (2*l + 1);
      iX[0] |= (i & (uint64_t)1 << (3*l + 2)) >> (2*l + 2);
    }
#if EXAFMM_HILBERT
    int N = 2 << (level - 1);
    int t = iX[2] >> 1;
    for (int d=2; d>0; d--) iX[d] ^= iX[d-1];
    iX[0] ^= t;
    for (int Q=2; Q!=N; Q<<=1) {
      int R = Q - 1;
      for (int d=2; d>=0; d--) {
        if (iX[d] & Q) iX[0] ^= R;
        else {
          t = (iX[0] ^ iX[d]) & R;
          iX[0] ^= t;
          iX[d] ^= t;
        }
      }
    }
#endif
    return iX;
  }

  ivec3 get3DIndex(vec3 X, int level, vec3 x0, real_t r0) {
    vec3 Xmin = x0 - r0;
    real_t dx = 2 * r0 / (1 << level);
    ivec3 iX;
    for (int d=0; d<3; d++) {
      iX[d] = floor((X[d] - Xmin[d]) / dx);
    }
    return iX;
  }

  vec3 getCoordinates(ivec3 iX, int level, vec3 x0, real_t r0) {
    vec3 Xmin = x0 - r0;
    real_t dx = 2 * r0 / (1 << level);
    vec3 X;
    for (int d=0; d<3; d++) {
      X[d] = (iX[d] + 0.5) * dx + Xmin[d];
    }
    return X;
  }
}
#endif
```

--------------------------------

### Configure exafmm-t Build

Source: https://exafmm.github.io/exafmm-t/compile.html

Navigates to the exafmm-t root directory and configures the build using autotools. The default configuration enables advanced SIMD instructions and double precision.

```bash
cd exafmm-t
./configure

```

--------------------------------

### Header File: include/test.h

Source: https://exafmm.github.io/exafmm-t/_sources/api/file_include_test.h.rst.txt

Overview of the test.h header file, detailing its dependencies, namespaces, and defined components.

```APIDOC
## File: include/test.h

### Description
This header file serves as a test component for the ExaFMM project. It includes necessary dependencies and defines specific namespaces, classes, and functions for testing purposes.

### Dependencies
- cassert
- exafmm_t.h
- fmm_base.h

### Namespaces
- exafmm_t

### Classes
- DummyFmm

### Functions
- namespaceexafmm__t_1adf72c12fd698ebf283bf02ae94d82ff7
```

--------------------------------

### File: build_list.h

Source: https://exafmm.github.io/exafmm-t/api/file_include_build_list.h.html

This section provides details about the build_list.h file, including its location and included files.

```APIDOC
## File: build_list.h

### Description
This file contains functions related to building hierarchical data structures for FMM calculations.

### Includes
- `exafmm_t.h`
- `fmm_base.h`
- `geometry.h`

### Namespaces
- `exafmm_t`

### Functions
- Template Function `exafmm_t::build_list`
- Template Function `exafmm_t::build_list_child_level`
- Template Function `exafmm_t::build_list_current_level`
- Template Function `exafmm_t::build_list_parent_level`
- Template Function `exafmm_t::set_colleagues(Node<T> *)`
- Template Function `exafmm_t::set_colleagues(Nodes<T>&)`
```

--------------------------------

### Template definitions for init_sources

Source: https://exafmm.github.io/exafmm-t/api/function_namespaceexafmm__t_1ad41a7b3f40be1d43245d44b63be08743.html

These templates define how particle sources are initialized based on the provided distribution and seed.

```cpp
template<> Bodies<complex_t> init_sources(int numBodies, const char *distribution, int seed)
```

```cpp
template<typename T> Bodies<T> init_sources(int numBodies, const char *distribution, int seed)
```

--------------------------------

### Function: exafmm_t::init_targets

Source: https://exafmm.github.io/exafmm-t/_sources/api/function_namespaceexafmm__t_1a50318156289412f1ccfd4c55db7004d5.rst.txt

Initializes target data structures for the exafmm_t project.

```APIDOC
## Function: exafmm_t::init_targets

### Description
Initializes targets for the exafmm_t project. Defined in file_include_dataset.h.

### Parameters
- **int** - Required - First parameter
- **const char *** - Required - Second parameter
- **int** - Required - Third parameter
```

--------------------------------

### Template Function exafmm_t::init_sources

Source: https://exafmm.github.io/exafmm-t/api/function_namespaceexafmm__t_1ad0528ffe62eca34477475f058ef3b075.html

Initializes a collection of bodies based on a specified distribution and random seed.

```APIDOC
## Function: exafmm_t::init_sources

### Description
Initializes a set of bodies for the FMM simulation using a specified distribution type and random seed.

### Parameters
- **numBodies** (int) - Required - The number of bodies to initialize.
- **distribution** (const char *) - Required - The type of distribution to apply (e.g., uniform, cube, etc.).
- **seed** (int) - Required - The random seed for the distribution generator.

### Returns
- **Bodies<T>** - Returns a collection of bodies initialized according to the provided parameters.
```

--------------------------------

### Function: exafmm_t::generate_surf2conv_up

Source: https://exafmm.github.io/exafmm-t/_sources/api/function_namespaceexafmm__t_1a3e073ac735c8a14905b5d1c55a55a780.rst.txt

Documentation for the generate_surf2conv_up function defined in geometry.h.

```APIDOC
## Function: exafmm_t::generate_surf2conv_up

### Description
Generates surface to conversion upward operators for the ExaFMM-t library.

### Endpoint
exafmm_t::generate_surf2conv_up(int)

### Parameters
#### Arguments
- **order** (int) - Required - The order of the expansion.
```

--------------------------------

### build_non_adaptive_tree.h File Details

Source: https://exafmm.github.io/exafmm-t/_sources/api/file_include_build_non_adaptive_tree.h.rst.txt

Provides an overview of the build_non_adaptive_tree.h header file, its dependencies, and its contents.

```APIDOC
## File: build_non_adaptive_tree.h

### Description
This file contains definitions related to building a non-adaptive tree structure.

### Includes
- ``exafmm_t.h``
- ``fmm_base.h``
- ``hilbert.h``

### Namespaces
- ``exafmm_t``

### Functions
- ``exafmm_t::exafmm_t_1ae5d771aab7f5b200a29da6f1bdca073a``
- ``exafmm_t::exafmm_t_1a845cf95f32c6b703f8b35605eac17646``
- ``exafmm_t::exafmm_t_1a68ab50d01815bca7c8b44e79b4282596``
- ``exafmm_t::exafmm_t_1a71b1b9efc409aed0bb812fe16448a407``
```

--------------------------------

### Hilbert Header Overview

Source: https://exafmm.github.io/exafmm-t/_sources/api/file_include_hilbert.h.rst.txt

Overview of the hilbert.h file structure, including dependencies and available functions within the exafmm_t namespace.

```APIDOC
## File: include/hilbert.h

### Description
This header file provides Hilbert curve related functionality for tree building in the ExaFMM-t project.

### Includes
- cstdlib
- exafmm_t.h
- stdint.h

### Namespaces
- exafmm_t

### Functions
- exafmm_t::HilbertKey (various overloads and implementations)

### Defines
- Various preprocessor definitions for Hilbert curve operations
```
Tokens:
Raw