Types

AbstractTree{T}

Supertype of every spatial tree in PhysicalTrees.jl. The type parameter T carries the particle scalar type (e.g. Float64, Unitful.Quantity).

A tree behaves like a one-element iterable (so for t in tree yields exactly one value) and length(tree) == 1. All search / communication routines are dispatched on the abstract type.

AbstractTree2D{T} <: AbstractTree{T}

Abstract supertype of every 2D spatial tree (PVector2D data). Currently no concrete subtype is shipped — 2D construction raises an informative error from init_octree.

AbstractTree3D{T} <: AbstractTree{T}

Abstract supertype of every 3D spatial tree (PVector data). The only concrete subtype shipped today is Octree.

AbstractOctree2D{T} <: AbstractTree2D{T}

Reserved for future 2D octree implementations. There is no concrete subtype in this version of PhysicalTrees.jl.

AbstractOctree3D{T} <: AbstractTree3D{T}

Abstract supertype of 3D octrees. The shipped concrete subtype is Octree.

AbstractOctreeNode{T}

Supertype of every node stored inside an Octree's treenodes array. Subtypes must store at minimum an ID, Father, DaughterID, geometric Center, SideLength, Mass, MassCenter, and a NextNode traversal pointer — see OctreeNode for the canonical concrete node.

AbstractOctreeNode2D{T} <: AbstractOctreeNode{T}

Reserved for future 2D node implementations. No concrete subtype ships today.

AbstractOctreeNode3D{T} <: AbstractOctreeNode{T}

Supertype of all 3D octree nodes. The shipped concrete subtype is OctreeNode.

OctreeNode{I<:Integer, POS, LEN, MASS} <: AbstractOctreeNode{I}

Concrete 3D octree node. OctreeNode is an immutable struct, so mutation is performed through Setfield.jl / BangBang.jl's setproperties!! (used internally throughout PhysicalTrees).

Fields (see the Octree page for the data layout):

TopNode{I<:Integer}

Top-level node in the Peano-Hilbert decomposition of the local data (an intermediate tree built during split_domain). It records the index of its Daughter in the local top-tree array, its starting Peano key (StartKey), its Count of particles, and the Blocks it occupies. TopNodes do not depend on the spatial dimension — the same struct is reused for 2D (bits=31) and 3D (bits=21).

Fields:

• Daughter::I — index of the first child in the local top-tree array (-1 for the root)
• Pstart::Int128 — Peano key of the first particle (Int128 to fit 2^(3*PeanoBits3D))
• Blocks::Int128 — number of DomainFac * SideLength blocks in the top-node
• Leaf::I — flag indicating this top-node is a leaf of the top-tree (1) or has children (0)
• Size::Int128 — number of particles inside the top-node
• StartKey::Int128 — Peano key where this top-node begins
• Count::Int128 — number of particles in the local task that fall inside this top-node

DomainNode{POS, VEL, MASS, LEN, B}

Per-domain pseudo-particle summary exchanged between workers during update. Each domain (one Peano leaf assigned to a worker) exports its MassCenter, velocity (Vel), Mass, largest smoothing length (MaxSoft) and bit-flag to every other worker so that remote subtrees can be queried as a single pseudo-particle.

Fields:

• MassCenter::POS — PVector mass-weighted center.
• Vel::VEL — center-of-mass velocity.
• Mass::MASS — total mass in the domain.
• MaxSoft::LEN — largest softening length in the domain.
• BitFlag::B — locality flags (reserved).

ExtNode{LEN, VEL}

Extra per-node aggregate that the search family reads in O(1) without touching the immutable OctreeNode itself. Indexed by the node id in the Octree's ExtNodes array and updated by update_local_data.

Fields:

• hmax::LEN — largest smoothing length among descendants (used by ngb_treefind_pairs to enlarge the search radius).
• vs::VEL — center-of-mass velocity of the subtree.

Octree{A, U, Len, Len_1, I, F, POS, VEL, MASS, B, Ext} <: AbstractOctree3D{A}

The concrete 3D octree shipped by PhysicalTrees.jl. The type parameters carry the particle container (A), the unit system (U), the global length / per-axis length types (Len / Len_1), the integer / float element types (I / F), and the types used for PVector / mass / bit-flags (POS, VEL, MASS, B, Ext).

Most users should never instantiate Octree directly — call octree(data; ...) instead. The fields and their layout are documented on the Octree page.

struct OctreeConfig

Stores config parameters for building octree

Notes:

1. NumDataBase is the decimal base of total number of data points.
2. Use ToptreeAllocFactor and TreeAllocFactor to control ToptreeAllocSection and TreeAllocSection respectively.

OctreeConfig(NumData::Integer; ToptreeAllocFactor, MaxTopnode, TopnodeFactor,
             TreeAllocFactor, MaxTreenode, ExtentMargin, PeanoBits3D, PeanoBits2D,
             epsilon, Periodic, BoxSize)

Constructor for OctreeConfig with sensible defaults derived from the total particle count NumData.

The allocation sections (ToptreeAllocSection / TreeAllocSection) are computed as NumDataBase * AllocFactor, where NumDataBase is the decimal base of NumData (e.g. NumData = 6000 → NumDataBase = 1000). A safety floor of 10 is applied when NumData < 100.

MaxTreenode defaults to NumData * 10 when NumData > 1000, otherwise 10000. All other knobs (BoxSize, Periodic, PeanoBits3D, …) accept the same defaults as the struct itself.

Example

cfg = OctreeConfig(6; Periodic = true, BoxSize = 2.0)