Reusable tree builder functions for integration tests. More...

Functions
Tree	build_tree3_adaptive_2d ()
	Build the adaptive 2D tree described by the tree3_stage*_fine_first_bfs.dot documentation files.

Tree	build_tree3_all_rows_2d ()
	Build a 2D variant where each depicted node in the tree3 diagram is represented by all rows with respect to its parent (3 cells in 2D), while Level 0 still starts from a single root node.

Tree	build_visualise_tree_split_example3_2d ()
	Build the 2D sparse tree used by `visualise_tree_split_example3.png`.

tuple[Tree, tuple[int, int]]	build_stage3_mixed_parent_case_2d ()
	Build a 2D tree where Stage III can promote a mixed parent.

Detailed Description

Reusable tree builder functions for integration tests.

Each function constructs and returns a fresh :class:Tree instance with all cells initially assigned to subtree 0. The trees are intentionally kept small and correspond to the reference diagrams under documentation/toolbox/loadbalancing/.

Function Documentation

◆ build_stage3_mixed_parent_case_2d()

tuple[Tree, tuple[int, int]] tree_builders.build_stage3_mixed_parent_case_2d ( )

Build a 2D tree where Stage III can promote a mixed parent.

The returned parent coordinates identify the level-0 parent whose children are configured with a dominant subtree assignment.

Definition at line 204 of file tree_builders.py.

◆ build_tree3_adaptive_2d()

Tree tree_builders.build_tree3_adaptive_2d ( )

Build the adaptive 2D tree described by the tree3_stage*_fine_first_bfs.dot documentation files.

The tree starts with a single root node on Level 0 and then embeds the 1D ternary structure in the first row of deeper 2D levels (all cells outside row 0 have weight=0).

Mapping: Level 0 (3x3): (0,0)=Root (single node) Level 1 (9x9): (0,0)=L1A (0,1)=L1B (0,2)=L1C Level 2 (27x27): (0,0)=L2A1 (0,1)=L2A2 (0,2)=L2A3 [childless leaf] (0,3)=L2B1 (0,4)=L2B2 (0,5)=L2B3 [childless leaf] (0,6)=L2C1 (0,7)=L2C2 (0,8)=L2C3 Level 3 (81x81): (0,0-2)=L3A1* (0,3-5)=L3A2* (0,6-8)=weight=0 [L2A3 has no children] (0,9-11)=L3B1* (0,12-14)=L3B2* (0,15-17)=weight=0 [L2B3 has no children] (0,18-20)=L3C1* (0,21-23)=L3C2* (0,24-26)=L3C3*

Total leaves initially (all in subtree 0): 21 finest-level leaves + 2 childless level-1 leaves = 23

The tree uses 4 total subtrees in the tests below.

Definition at line 16 of file tree_builders.py.

◆ build_tree3_all_rows_2d()

Tree tree_builders.build_tree3_all_rows_2d ( )

Build a 2D variant where each depicted node in the tree3 diagram is represented by all rows with respect to its parent (3 cells in 2D), while Level 0 still starts from a single root node.

Representation rule in 2D:

For each conceptual parent-child edge, one conceptual child node is represented as a vertical stripe of 3 cells in the parent's 3x3 child patch.
Conceptual child indices 0,1,2 map to local child columns 0,1,2.

This means all represented non-leaf parents have all 9 children present, which allows Stage III to optimise mixed parents at Level 1.

Definition at line 80 of file tree_builders.py.

◆ build_visualise_tree_split_example3_2d()

Tree tree_builders.build_visualise_tree_split_example3_2d ( )

Build the 2D sparse tree used by visualise_tree_split_example3.png.

The tree has 10 leaves in total and is arranged as a single branch that is refined twice on the left-most child path:

4 finest-level leaves on the deepest branch
3 level-2 leaves on the middle branch
3 level-1 leaves directly under the root

This is the example that splits best into subtrees 4-3-3.