orrery::solvers::TreeParameters Struct Reference

The choices that decide what the tree costs and how accurate it is. More...

#include <orrery/solvers/octree.hpp>

Public Attributes
core::Real	opening_angle {static_cast<core::Real>(0.5)}
	The opening angle, in the sense of the criterion in octree.hpp's acceptance radius: a cell of size s is accepted at distance d when d >= s / theta + delta, where delta is the offset of its centre of mass from its geometric centre.
core::Index	leaf_capacity {32}
	The most particles a cell may hold and still be a leaf.
bool	quadrupole {false}
	Whether to compute and use the quadrupole moment of each cell.

Detailed Description

The choices that decide what the tree costs and how accurate it is.

They live with the tree rather than with the solver because all three are spent during construction: the opening angle is folded into every node's acceptance radius, the leaf capacity decides where subdivision stops, and the quadrupole switch decides whether the moments are computed at all.

Member Data Documentation

opening_angle

core::Real orrery::solvers::TreeParameters::opening_angle {static_cast<core::Real>(0.5)}

The opening angle, in the sense of the criterion in octree.hpp's acceptance radius: a cell of size s is accepted at distance d when d >= s / theta + delta, where delta is the offset of its centre of mass from its geometric centre.

Half a radian is the value the literature settles on and the value this project defaults to, and docs/performance/barnes_hut.md measures the error and the cost either side of it rather than citing anyone.

Restricted to [0, 1]. The upper bound is not a matter of taste: above one, a cell can be accepted while the particle being accelerated is still inside it, which would have the particle attract itself through its own cell's centre of mass. A larger value is reduced to one rather than rejected, on the same terms as DirectSolver::select_kernel, and the solver reports what it settled on.

leaf_capacity

core::Index orrery::solvers::TreeParameters::leaf_capacity {32}

The most particles a cell may hold and still be a leaf.

The trade is between two costs that move in opposite directions. Small leaves mean more nodes to build, more nodes to walk and a deeper tree; large leaves mean more pairs computed directly at the bottom of every walk. The optimum is not a property of the algorithm but of how fast the machine computes a pair against how fast it walks a node, and on this machine the pair is computed four at a time by the AVX2 kernel of Phase 7, which pushes the answer higher than the eight or sixteen a scalar implementation would choose.

Thirty-two is measured rather than assumed, in docs/performance/barnes_hut.md. Values below one are treated as one.

quadrupole

bool orrery::solvers::TreeParameters::quadrupole {false}

Whether to compute and use the quadrupole moment of each cell.

Off by default. It is an accuracy option rather than an improvement: it costs memory per node, arithmetic per accepted cell and a second aggregation during construction, and it buys about an order of magnitude of accuracy at a fixed opening angle. Whether that is a good trade depends on whether the same accuracy is cheaper to buy by opening the angle instead, which is a question about the configuration and the machine and is measured in docs/performance/barnes_hut.md rather than settled here. ADR-0024 records the reasoning.

---

The documentation for this struct was generated from the following file:

• orrery/solvers/octree.hpp