Data structure for adaptive mesh trees in Peano load balancing. More...

Inheritance diagram for api.Tree.Tree:

Collaboration diagram for api.Tree.Tree:

Public Member Functions
	__init__ (self, name, dimension, domain_offset, domain_size)
	Initialize a new Tree object.

	number_of_subtrees (self)

	number_of_leaves (self)

	__str__ (self)

	read_in_tree_from_arrays (self, input_tree_arrays, max_level, weighted=False)

	read_in_level_array (self, input_level_arrays, subtree_id, level)

	read_in_tree_from_artificial (self, input_artificial_arrays, max_level, weighted=False)

	update_split_pattern (self)

	update_weight (self)

Protected Attributes
	_name

	_dimension

	_domain_offset

	_domain_size

	_tree_arrays

	_leaf_count

	_subtree_count

	_split_pattern

	_max_level

	_weighted

Detailed Description

Data structure for adaptive mesh trees in Peano load balancing.

This class represents adaptive mesh trees as sequences of grid levels, where each level is stored as a 2D or 3D array. The tree structure is designed to support offline decomposition and load balancing analysis.

Tree Structure Overview

The main content of this class is a series of 2D or 3D arrays with dimension sizes of 3^(level+1), where level ranges from 1 to the maximum depth of the tree. Each entry in the arrays is a tuple of 2 numbers:

Weight: 1 if the cell exists, 0 if it doesn't (enables representation of adaptive meshes)
Subtree ID: Integer indicating which compute resource/subtree owns the cell

Data Representation Examples

2D Example: Uniform 2-level tree with 4 subtrees

Level 1 (3x3 array):

{(1,0), (1,0), (1,1)
 (1,1), (1,1), (1,3)
 (1,2), (1,2), (1,3)}

Level 2 (9x9 array):

{(1,0), (1,0), (1,0), (1,0), (1,0), (1,0), (1,1), (1,1), (1,1),
 (1,0), (1,0), (1,0), (1,0), (1,0), (1,0), (1,1), (1,1), (1,1),
 (1,0), (1,0), (1,0), (1,0), (1,0), (1,0), (1,1), (1,1), (1,1),
 (1,1), (1,1), (1,1), (1,1), (1,1), (1,1), (1,3), (1,3), (1,3),
 (1,1), (1,1), (1,1), (1,1), (1,1), (1,1), (1,3), (1,3), (1,3),
 (1,1), (1,1), (1,1), (1,1), (1,1), (1,1), (1,3), (1,3), (1,3),
 (1,2), (1,2), (1,2), (1,2), (1,2), (1,2), (1,3), (1,3), (1,3),
 (1,2), (1,2), (1,2), (1,2), (1,2), (1,2), (1,3), (1,3), (1,3),
 (1,2), (1,2), (1,2), (1,2), (1,2), (1,2), (1,3), (1,3), (1,3)}

Adaptive Mesh Representation

For adaptive meshes where some regions are not refined, entries have weight 0:

   Level 1: {(1,0), (0,0), (1,0)    # Middle cell not refined
(1,0), (1,0), (1,0)
(1,0), (1,0), (1,0)}
 
   Level 2: Corresponding 9x9 array with zeros in the middle 3x3 block

Key Properties

Hierarchical Structure: Each level refines the previous by factor of 3 in each dimension
Adaptive Support: Zero weights represent non-existent cells in adaptive meshes
Load Balancing Ready: Subtree IDs enable domain decomposition analysis

Usage in Load Balancing

This data structure supports various load balancing operations:

Tree Analysis: Count leaf nodes, analyze refinement patterns
Splitting Strategies: Redistribute subtree assignments for load balancing
Visualization: Generate spatial representations of tree structure
Export: Create YAML outputs for integration with Peano's hardcoded load balancer

Coordinate System

2D: Arrays use (a,b) indexing where a,b ∈ [0, 3^(level+1)-1]
3D: Arrays use (a,b,c) indexing where a,b,c ∈ [0, 3^(level+1)-1]
Level Numbering: Levels start from 0 (coarsest) to max_level-1 (finest)
Array Sizes: Level k has size 3^(k+1) in each dimension

Important Notes

The lowest level is 1 with size 3x3 (2D) or 3x3x3 (3D)
All arrays are stored as numpy arrays with dtype=object for tuple storage
Tree metadata (leaf count, split patterns) is automatically updated after modifications
Domain offset and size define the physical coordinate mapping

Related Components

This class works with:

GridPatchFileReader: Reads Peano grid files into Tree format
RegularGridGenerator: Creates artificial uniform trees for testing
SplitTrees: Implements splitting algorithms for load balancing
TreeVisualizer: Generates visual representations of tree structures

Example Usage

# Create a tree from artificial regular grid
tree = RegularGridGenerator("test", max_level=3, dimensions=2)
 
# Apply load balancing splitting
split_tree(tree, number_of_subtrees=3)
 
# Generate visualization
TreeVisualizer(tree, dimensions=2, filename="balanced_tree")
 
# Export to YAML
generate_tree_yaml(tree, "output.yaml")

Definition at line 8 of file Tree.py.

Constructor & Destructor Documentation

◆ init()

api.Tree.Tree.__init__	(	self,
		name,
		dimension,
		domain_offset,
		domain_size
	)

Initialize a new Tree object.

Args: name (str): Descriptive name for the tree (e.g., "RegularGrid" or filename) dimension (int): Spatial dimension (2 for 2D, 3 for 3D) domain_offset (tuple): Physical coordinates of domain origin domain_size (tuple): Physical size of domain in each dimension

Definition at line 114 of file Tree.py.