Overview

family_tree - useful, potentially useful, and not-so-useful information 
	     about enzo AMR hierarchies.

Author: Britton D. Smith <brittonsmith@gmail.com>
Date: January 26, 2009.
Affiliation: Michigan State University
Homepage: http://hub.yt-project.org/

Usage: ./family_tree [flags] <dataset>
        -h: print this help output.
        -na: skip common ancestor calculation (speeds up hierarchy parsing for large simulations).
        -s: enter interactive shell.  Type 'help' for a list of shell commands.

family_tree is an Enzo hierarchy file parser that provides an informative view of 
the structure of an AMR hierarchy in a simulation dataset.  A non-interactive call 
to family_tree will return the following:
   	      - the total number of grids, cells, and particles in the dataset.
	      - the maximum refinement level.
	      - for each level in the AMR hierarchy:
	      	    - the number of grids, cells, and particles.
		    - the fractional volume of the domain refined to that level.
		    - the grid and grid level of the nearest common ancestor of all 
		      grids on that level.  This calculation can be expensive 
		      for large simulations with AMR everywhere, often yielding 
		      nothing interesting.  It can be disabled with the -na 
		      option.

In interactive mode (launched with the -s option), the following additional 
information can be gathered:
   	      - grid <number> - specific information on a single grid:
	      	    - level.
		    - dimension.
		    - left and right edges.
		    - number of cells and particles.
		    - full ancestry.
		    - siblings (grids at same level with same parent).
		    - children.
		###################################################################
		Grid: 1438
		Level: 11
		Dimension: 32 28 16
		Left Edge: 0.51114654541016 0.48704528808594 0.4981689453125
		Right Edge: 0.51126861572266 0.48715209960938 0.49822998046875
		Cells: 24.29^3
		Particles: 2.00^3
		Parent: 1437 -> 1435 -> 1431 -> 1424 -> 1415 -> 1394 -> 1302 -> 1194 -> 1094 -> 1046 -> 22
		Siblings: 1438 - 1440
		Children: 1541 - 1544
		###################################################################

	      - spot <x> <y> <z> - full ancestry of all grids covering or 
	      	     	     	   bordering a coordinate.
		###################################################################
		Coordinates: (0.5,0.5,0.5)
		Grid coverage by level is:
		   0 ||    1 ||    2 ||    3 ||    4
		====================================
		  12 -> 6462 -> 6634 -> 7080 -> 7389
		  13 -> 5918 -> 6050 -> 6238 -> 6330
		  14 -> 5302 -> 5422 -> 5550 -> 5646
		  15 -> 4774 -> 4846 -> 4932 -> 4964
		  20 -> 3965 -> 4073 -> 4286 -> 4444
		  21 -> 2917 -> 2977 -> 3054 -> 3140
		  22 -> 1046 -> 1094 -> 1194 -> 1302
		  23 ->   40 ->   48 ->   56 ->   67
		###################################################################

	      - trace <level> - trace all grids on level back to a 
	      	      	      	common ancestor.
		###################################################################
		Tracing family lines from level 19.
		At level 19. 13 groups stem from 4 family lines.
		At level 18. 4 groups stem from 3 family lines.
		At level 17. 3 groups stem from 3 family lines.
		At level 16, 3 groups stem from grid 1699 on level 15
		###################################################################

	      - level <level> - show all grids on a level.
	        ###################################################################
		Grids from level 20: 1730, 1732, 1757-1758
		Number of unique parents: 3
		###################################################################