# Architecture Overview of fmsolvr

This document provides a high-level overview of the structure of the *fmsolvr* framework.
Its purpose is to help developers understand how the main components of the solver interact.

The framework implements numerical algorithms based on the **Fast Multipole Method (FMM)**
and is structured as a modular C++ code base.

## Design Principles

The architecture follows several guiding principles:

- modular separation of algorithmic components
- clear boundaries between infrastructure and numerical kernels
- portability across compilers and hardware architectures
- isolation of performance‑critical code

## Main Modules

### operator

This module contains the core numerical operators used by the fast multipole method.
These operators implement transformations between multipole expansions, local expansions,
and particle interactions.

### simd

Provides vectorized numerical kernels optimized for modern CPU instruction sets.

### math

Contains mathematical utilities used throughout the solver, including vector operations
and numerical helper routines.

### container

Defines core data structures used to store particles, expansions, and related data.

### tree

Implements hierarchical spatial data structures required by the fast multipole method.

### p2p

Contains direct particle‑to‑particle interaction kernels used for near‑field interactions.

### util

Provides general helper utilities and configuration infrastructure used across the project.

## Solver Drivers

Executable driver programs such as `coulomb.cc` provide entry points for running solver experiments.
They typically perform the following steps:

1. initialize particle data
2. build hierarchical tree structures
3. compute multipole expansions
4. apply interaction operators
5. evaluate results or run benchmarks

Driver programs should remain separate from reusable library code.

## Build System

The project uses **CMake** to configure and build all components including the solver,
unit tests, and microbenchmarks.