Utilities for Consistent-Trees Catalogues

Provides several useful utility functions that work with tree catalogues generated by Consistent-Trees.

uchuutools.ctrees_utils.read_locations_and_forests(forests_fname, locations_fname, rank=0)

Returns a numpy structured array that contains both the forest and tree level info.

Parameters:

• forests_fname (string, required) – The name of the file containing forest-level info like the Consistent-Trees ‘forests.list’ file
• locations_fname (string, required) – The name of the file containing tree-level info like the Consistent-Trees ‘locations.dat’ file
• rank (integer, optional, default:0) – An integer identifying which task is calling this function. Only used in status messages

Returns:

trees_and_locations (A numpy structured array) – A numpy structured array containing the fields <TreeRootID ForestID Filename FileID Offset TreeNbytes> The array is sorted by (ForestID, Filename, Offset) in that order. This sorting means that all trees belonging to the same forest will appear consecutively regardless of the file that the corresponding tree data might appear in. The number of elements in the array is equal to the number of trees.

Note: Sorting by Filename is implemented by an equivalent, but faster sorting on FileID.

uchuutools.ctrees_utils.get_aggregate_forest_info(trees_and_locations, rank=0)

Returns forest-level information from the tree-level information supplied.

Parameters:

• trees_and_locations (numpy structured array, required) – A numpy structured array that contains the tree-level information. Should be the output from the function read_locations_and_forests()
• rank (integer, optional, default:0) – An integer identifying which task is calling this function. Only used in status messages

Returns:

forest_info (A numpy structured array) – The structured array contains the fields ['ForestID', 'ForestNhalos', 'Input_ForestNbytes', 'Ntrees'] The ‘ForestNhalos’ field is set to 0, and is populated as the trees are processed. The number of elements in the array is equal to the number of forests.

uchuutools.ctrees_utils.get_all_parallel_ctrees_filenames(fname)

Returns three filenames corresponding to the 'forests.list', 'locations.dat', and 'tree_*.dat' files assuming the naming convention the Uchuu collaboration’s parallel Consistent-Trees code

Parameters:fname (string, required) – A filename specifying the tree data file for a parallel Consistent-Trees soutput Returns:forests_file, locations_file, treedata_file (strings, filenames) – The filenames corresponding to the 'forests.list', 'locations.dat' and the 'tree_*_*_*.dat' file generated using the convention of the Uchuu collaboration. The convention is:

Standard CTrees	Parallel CTrees
’forests.list’	’<prefix>.forest’
’locations.dat’	’<prefix>.loc’
’tree_*_*_*.dat’	’<prefix>.tree’

uchuutools.ctrees_utils.check_forests_locations_filenames(filenames)

Accepts two filenames (in any order) and checks whether the files contain the correct data as expected in ‘forests.list’, ‘locations.dat’ and returns the files as (equivalent to) ‘forests.list’ and ‘locations.dat’

Parameters:filenames (list of two filenames, string, required) – List containing two filenames corresponding to the standard ‘forests.list’ and ‘locations.dat’ (in any order, i.e., both [‘forests.list’, ‘locations.dat’] and [‘locations.dat’, ‘forests.list’] are valid) Returns:forests_file, locations_file (strings, filenames) – The filenames equivalent to the ‘forests.list’, ‘locations.dat’ (in that order)

uchuutools.ctrees_utils.validate_inputs_are_ctrees_files(ctrees_filenames, base_metadata=None, base_version=None, base_input_catalog_type=None)

Checks the files contain Consistent-Trees catalogues derived from the same simulation and Consistent-Trees configuration.

Parameters:

ctrees_filenames (list of filenames, string, required) – The input filenames (potentially) containing Consistent-Trees catalogues.

Note: Only unique filenames within this list are checked

Returns:

True on successful validation, ValueError otherwise

uchuutools.ctrees_utils.get_treewalk_dtype_descr()

Returns the description for the additional fields to add to the forest for walking the mergertree

Parameters:None Returns:mergertree_descr (list of tuples) – A list of tuples containing the names and datatypes for the additional columns needed for walking the mergertree. This list can be used to create a numpy datatype suitable to contain the additional mergertree indices

uchuutools.ctrees_utils.add_tree_walk_indices(forest, rank=0)

Adds the various mergertree walking indices and IDs. These include indices to access the host FOF halo<->subhalo hierarchy, and the progenitor-descendant hierarchy.

The mergertree indices are filled in-place and no additional return occurs. The specific indices are listed in the function get_treewalk_dtype_descr()

Parameters:

• forest (numpy structured array, required) – An array containing all halos from the same forest
• rank (integer, optional, default=0) – The unique identifier for the current task. Only used within an error statement

Returns:

True on successful completion