# USER_GUIDE.md
## Interface and Usage Guide for fmsolvr

This document describes how to build, run, and use the *fmsolvr* framework from a user perspective.
It explains the main APIs available in Version C and references the scientific literature behind the algorithms.

Primary references:
Greengard, L., Rokhlin, V. (1987). A Fast Algorithm for Particle Simulations. Journal of Computational Physics.
Gumerov, N., Duraiswami, R. (2004). Fast Multipole Methods for the Helmholtz Equation in Three Dimensions.
Jackson, J. (1999). Classical Electrodynamics (3rd ed.).

---

# Building

Typical build:

git clone <repository-url>
cd fmsolvr
mkdir build
cd build
cmake ..
make

---

# Running the Solver

Example driver program:

./coulomb

The program performs the following steps:

1. create particle data
2. construct spatial tree
3. compute multipole expansions
4. evaluate interactions
5. compute potentials and forces

---

# Core APIs

## FMMBaseCoulomb

Header:
include/fmsolvr/fmmbase.hpp

template <typename Real, typename BoxID, template <typename> class SIMD_Engine, typename Alloc>
class FMMBaseCoulomb;

Defines solver types including:
- real number type
- coordinate type
- multipole coefficients
- local expansion coefficients

Corresponds to the formulation of the FMM described by Greengard & Rokhlin (1987).

---

## FMMParticleHandle

Header:
include/fmsolvr/handle_particle.hpp

template <typename FMMTypes>
class FMMParticleHandle;

Constructor:

FMMParticleHandle(simulationbox_type simbox, size_type n, size_type depth);

Important methods:

ordered_particles()
box_particle_offset()
monopole_dipole()
total_abs_strength()

Stores reordered particle data used in the hierarchical tree.

---

## FMMParticleInteractionHandle

Also defined in handle_particle.hpp.

Provides storage for results:

potential_nf()
potential_ff()
efield_nf()
efield_ff()
force_nf()
force_ff()
Ec()
compute_forces_energy()

These values represent the electrostatic potential and forces of the particle system.

---

## FMMTreeHandle

Header:
include/fmsolvr/handle_tree.hpp

template <typename FMMTypes>
class FMMTreeHandle;

Methods:

tree_omega()
tree_mu()
depth()
p()

Stores the hierarchical multipole and local expansion coefficients.

---

## FMMPrecomputedDataHandle

Header:
include/fmsolvr/handle_precomputed.hpp

Provides precomputed translation operators:

m2m_operator_cube()
m2l_operator_cube()
l2l_operator_cube()

Corresponds to the operators described in Greengard & Rokhlin (1987) and
Gumerov & Duraiswami (2004).

---

## FMMPrecomputedRotationDataHandle

Header:
include/fmsolvr/handle_precomputed_p3.hpp

Provides rotation generators:

RotationGeneratorM2M()
RotationGeneratorM2L()
RotationGeneratorL2L()

These implement rotations of spherical harmonic expansions.

---

## FMMHandle

Header:
include/fmsolvr/fmm_handle.hpp

template <typename FMMTypes>
class FMMHandle;

Aggregates all solver components:

- particle storage
- tree storage
- precomputed operators
- rotation data

Important methods:

particle_handle()
tree_omega()
tree_mu()
m2m_operator_cube()
m2l_operator_cube()
l2l_operator_cube()

---

# Particle Distribution

Header:
include/fmsolvr/distribute_particles.hpp

template <typename ParticleHandle, typename InputParticles>
void distribute_particles(ParticleHandle&, InputParticles&);

Assigns particles to spatial tree cells and sorts them for efficient traversal.

---

# Far-Field Evaluation

Header:
include/fmsolvr/farfield_interaction.hpp

farfield_interaction(q, xyz, mu, ref_point, expansion_order)

Returns potential and force vector computed from a local expansion.

---

# Minimal Usage Example

using FMMTypes = fmsolvr::FMMBaseCoulomb<double, BoxID, SIMD>;

FMMParticleHandle<FMMTypes> particles(simbox, N, depth);
distribute_particles(particles, inputParticles);

FMMParticleInteractionHandle<FMMTypes> interactions(particles);
FMMTreeHandle<FMMTypes> tree(depth, p);

// create precomputed handles

FMMHandle<FMMTypes> fmm(interactions, precomp, rotprecomp, tree,
                        depth, ws, p, false, std::cout);

Results are available through:

potential_nf()
potential_ff()
efield_nf()
force_nf()

---

# Additional Documentation

PROJECT_OVERVIEW.md
ARCHITECTURE.md
CODING_GUIDELINES.md
DEVELOPER_ONBOARDING.md