Clump FindingΒΆ

The clump finder uses a contouring algorithm to identified topologically disconnected structures within a dataset. This works by first creating a single contour over the full range of the contouring field, then continually increasing the lower value of the contour until it reaches the maximum value of the field. As disconnected structures are identified as separate contours, the routine continues recursively through each object, creating a hierarchy of clumps. Individual clumps can be kept or removed from the hierarchy based on the result of user-specified functions, such as checking for gravitational boundedness. A sample recipe can be found in Identifying Clumps.

The clump finder requires a data object (see Data Objects) and a field over which the contouring is to be performed.

import yt
from yt.analysis_modules.level_sets.api import *

ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")

data_source = ds.disk([0.5, 0.5, 0.5], [0., 0., 1.],
                      (8, 'kpc'), (1, 'kpc'))

master_clump = Clump(data_source, ("gas", "density"))

At this point, every isolated contour will be considered a clump, whether this is physical or not. Validator functions can be added to determine if an individual contour should be considered a real clump. These functions are specified with the Clump.add_validator function. Current, two validators exist: a minimum number of cells and gravitational boundedness.

master_clump.add_validator("min_cells", 20)

master_clump.add_validator("gravitationally_bound", use_particles=False)

As many validators as desired can be added, and a clump is only kept if all return True. If not, a clump is remerged into its parent. Custom validators can easily be added. A validator function must only accept a Clump object and either return True or False.

def _minimum_gas_mass(clump, min_mass):
    return (clump["gas", "cell_mass"].sum() >= min_mass)
add_validator("minimum_gas_mass", _minimum_gas_mass)

The add_validator function adds the validator to a registry that can be accessed by the clump finder. Then, the validator can be added to the clump finding just like the others.

master_clump.add_validator("minimum_gas_mass", ds.quan(1.0, "Msun"))

The clump finding algorithm accepts the Clump object, the initial minimum and maximum of the contouring field, and the step size. The lower value of the contour finder will be continually multiplied by the step size.

c_min = data_source["gas", "density"].min()
c_max = data_source["gas", "density"].max()
step = 2.0
find_clumps(master_clump, c_min, c_max, step)

After the clump finding has finished, the master clump will represent the top of a hierarchy of clumps. The children attribute within a Clump object contains a list of all sub-clumps. Each sub-clump is also a Clump object with its own children attribute, and so on.

A number of helper routines exist for examining the clump hierarchy.

# Write a text file of the full hierarchy.
write_clump_index(master_clump, 0, "%s_clump_hierarchy.txt" % ds)

# Write a text file of only the leaf nodes.
write_clumps(master_clump,0, "%s_clumps.txt" % ds)

# Get a list of just the leaf nodes.
leaf_clumps = get_lowest_clumps(master_clump)

Clump objects can be used like all other data containers.

print(leaf_clumps[0]["gas", "density"])
print(leaf_clumps[0].quantities.total_mass())

The writing functions will write out a series or properties about each clump by default. Additional properties can be appended with the Clump.add_info_item function.

master_clump.add_info_item("total_cells")

Just like the validators, custom info items can be added by defining functions that minimally accept a Clump object and return a string to be printed.

def _mass_weighted_jeans_mass(clump):
    jeans_mass = clump.data.quantities.weighted_average_quantity(
        "jeans_mass", ("gas", "cell_mass")).in_units("Msun")
    return "Jeans Mass (mass-weighted): %.6e Msolar." % jeans_mass
add_clump_info("mass_weighted_jeans_mass", _mass_weighted_jeans_mass)

Then, add it to the list:

master_clump.add_info_item("mass_weighted_jeans_mass")

By default, the following info items are activated: total_cells, cell_mass, mass_weighted_jeans_mass, volume_weighted_jeans_mass, max_grid_level, min_number_density, max_number_density, and distance_to_main_clump.

Clumps can be visualized using the annotate_clumps callback.

prj = yt.ProjectionPlot(ds, 2, ("gas", "density"),
                        center='c', width=(20,'kpc'))
prj.annotate_clumps(leaf_clumps)
prj.save('clumps')