pynbody.halo.adaptahop.AdaptaHOPCatalogue

class pynbody.halo.adaptahop.AdaptaHOPCatalogue(sim, filename=None, read_contamination=None, longint=None)

Bases: BaseAdaptaHOPCatalogue

Attributes:

base

The snapshot object that this halo catalogue is based on.

Methods

complete_keys([load_all_if_required])	Return an array of the halo numbers which can actually be retrieved from the snapshot.
contains(halo_number)	Deprecated alias; instead of h.contains(number) use number in h.
from_portable_state(state, sim)	Recreate a halo catalogue from a state dictionary, attaching it to the specified simulation.
get_complete_mask([load_all_if_required])	Return a boolean mask, in halo index order, of the halos which can be retrieved from the snapshot.
get_dummy_halo(halo_number)	Return a DummyHalo object containing only the halo properties, no particle information
get_group_array([family, use_index, fill_value])	Return an array with an integer for each particle in the simulation, indicating the halo of that particle.
get_portable_state()	Express the entire catalogue as numpy arrays and python primitives.
get_properties_all_halos([with_units])	Returns a dictionary of properties for all halos.
get_properties_one_halo(i)	Returns a dictionary of properties for a single halo, given a halo_number
is_complete(halo_number[, load_all_if_required])	Return True if the specified halo can actually be retrieved from the snapshot.
iter_subclasses()	Iterate over all subclasses of this class, recursively.
iter_subclasses_with_priority(priority)	Iterate over all subclasses, starting with the given priorities
keys()	Return an array of all halo numbers in the catalogue, whether or not they can be loaded.
load_all()	Loads all halos, which is normally more efficient if a large fraction of them will be accessed.
load_copy(halo_number)	Load a fresh SimSnap with only the particles in specified halo
physical_units([distance, velocity, mass, ...])	Converts all arrays' units to be consistent with the distance, velocity, mass basis units specified.
precalculate()	Deprecated alias for load_all()

convert_i8b

__init__(sim, filename=None, read_contamination=None, longint=None)

Initialise a AdaptaHOP catalogue.

Parameters:

• sim (SimSnap) – The snapshot to which this catalogue is attached.

• filename (str, optional) – The filename of the AdaptaHOP catalogue (path/to/tree_bricksXXX). If not specified, the code will attempt to find the catalogue in the simulation directory.

• read_contamination (bool, optional) – Whether to read information about contamination of each halo. If not specified, the code will attempt to detect the format. Note that if specifying read_contamination, longint must also be specified.

• longint (bool, optional) – Whether to read 64-bit integers. If not specified, the code will attempt to detect the format. Note that if specifying longint, read_contamination must also be specified.

property base: SimSnap

The snapshot object that this halo catalogue is based on.

complete_keys(load_all_if_required=True) → NDArray[int]

Return an array of the halo numbers which can actually be retrieved from the snapshot.

This is a subset of keys(), in the same order, from which halos referring to particles that are not present in the snapshot have been excluded. Accessing such halos raises an IncompleteHaloError; this normally happens only if the snapshot has been partially loaded.

Note that halo properties remain available for all halos, including incomplete ones; it is only access to the particles which fails.

Some catalogue formats express halo membership through an array covering only the particles which were loaded, such as a halo number per particle, and so are unable to tell whether the halo finder assigned further particles which are absent. These report all their halos as complete, and issue a RuntimeWarning to that effect. (Formats which instead identify their particles by position within the snapshot cannot be used with a partially loaded snapshot at all; they refuse to load.)

Added in version 2.7.0.

Parameters:

load_all_if_required (bool) – Establishing which halos are complete requires the particle lists for all halos, so load_all() is called if it has not been already. If this is undesirable (e.g. because the catalogue is very large), pass False to raise a RuntimeError instead.

contains(halo_number: int) → bool

Deprecated alias; instead of h.contains(number) use number in h.

classmethod from_portable_state(state: dict, sim: SimSnap) → HaloCatalogue

Recreate a halo catalogue from a state dictionary, attaching it to the specified simulation.

Added in version 2.7.0.

Parameters:

• state (dict) – A dictionary previously returned by get_portable_state(), possibly having been transferred from another process.

• sim (SimSnap) – The simulation to attach the catalogue to. It must have the same particle ordering as the simulation the state was generated from, since halo membership is expressed as offsets into it.

Returns:

A halo catalogue which behaves like the original, but does not refer to the halo finder’s files.

Return type:

PortableHaloCatalogue

get_complete_mask(load_all_if_required=True) → NDArray[bool]

Return a boolean mask, in halo index order, of the halos which can be retrieved from the snapshot.

This is the underlying information from which complete_keys() and is_complete() are derived. Since it is in index order, it can be used to filter the arrays returned by get_properties_all_halos(). (See the class documentation for the distinction between halo numbers and indices.)

See complete_keys() for the meaning of the load_all_if_required argument. The returned array is cached and read-only.

Added in version 2.7.0.

get_dummy_halo(halo_number) → DummyHalo

Return a DummyHalo object containing only the halo properties, no particle information

get_group_array(family=None, use_index=False, fill_value=-1)

Return an array with an integer for each particle in the simulation, indicating the halo of that particle.

If there are multiple levels (i.e. subhalos), the number returned corresponds to the lowest level, i.e. the smallest subhalo.

Parameters:

• family (str, optional) – If specified, return only the group array for the specified family.

• use_index (bool, optional) – If True, return the halo index rather than the halo number. (See the class documentation for the distinction between halo numbers and indices.)

• fill_value (int, optional) – The value to fill for particles not in any halo.

get_portable_state() → dict

Express the entire catalogue as numpy arrays and python primitives.

The result is a dictionary whose values are numpy arrays, python primitives (such as strings and integers), or nested dictionaries of the same. Nothing in it is tied to the present process, or to the halo finder’s files, so it may be transferred elsewhere – for example to another process, by putting the arrays into shared memory. The recipient does not need to know the role of any individual array; it needs only to reproduce the structure at the other end, where from_portable_state() turns it back into a live halo catalogue attached to a specified simulation.

The state includes the halo numbering, the particles belonging to each halo, any information about particles that are missing from the snapshot (see IncompleteHaloError), whether this catalogue is able to detect such particles at all (_can_determine_completeness, so that a catalogue which cannot does not appear to have become able to once transferred), and the halo finder properties that are available from get_properties_all_halos(). Properties which are only available one halo at a time, i.e. those provided by catalogues which implement get_properties_one_halo() without get_properties_all_halos(), are not included.

Note that halo membership is expressed as offsets into the snapshot, so the state is only meaningful alongside a snapshot with the same particle ordering as the present one.

Added in version 2.7.0.

get_properties_all_halos(with_units=True) → dict

Returns a dictionary of properties for all halos.

If with_units is True, the properties are returned as SimArrays with units if possible. Otherwise, numpy arrays are returned.

Note that the returned properties are in contiguous arrays, and as a result may be in a different order to the halo numbers which are used to access individual halos. To map between halo numbers and properties, use the .number_mapper object; or access individual property dictionaries by halo number using get_properties_one_halo.

get_properties_one_halo(i)

Returns a dictionary of properties for a single halo, given a halo_number

is_complete(halo_number, load_all_if_required=True) → bool

Return True if the specified halo can actually be retrieved from the snapshot.

See complete_keys() for more information, including the meaning of the load_all_if_required argument.

Added in version 2.7.0.

classmethod iter_subclasses() → Iterable[type]

Iterate over all subclasses of this class, recursively.

This is used by HaloCatalogue and SimSnap to find a suitable loader for a given file.

classmethod iter_subclasses_with_priority(priority: Iterable[str | type]) → Iterable[type]

Iterate over all subclasses, starting with the given priorities

The priorities can be provided either as a string or a class

keys() → NDArray[int]

Return an array of all halo numbers in the catalogue, whether or not they can be loaded.

If the snapshot has been partially loaded, some of these halos may refer to particles that are not present, and cannot be retrieved; see complete_keys().

The returned array is read-only, since it may be a view of the catalogue’s internal numbering.

Changed in version 2.7.0: A read-only numpy array is returned. Previously this was whatever the catalogue’s number mapper held, and was writable, so code which modified it in place must now take a copy first.

load_all()

Loads all halos, which is normally more efficient if a large fraction of them will be accessed.

load_copy(halo_number)

Load a fresh SimSnap with only the particles in specified halo

This relies on the underlying SimSnap being capable of partial loading.

physical_units(distance='kpc', velocity='km s^-1', mass='Msol', persistent=True, convert_parent=False)

Converts all arrays’ units to be consistent with the distance, velocity, mass basis units specified.

Parameters:

• distance (string (default = 'kpc')) – The distance unit to convert to.

• velocity (string (default = 'km s^-1')) – The velocity unit to convert to.

• mass (string (default = 'Msol')) – The mass unit to convert to.

• persistent (boolean (default = True)) – Apply units change to future lazy-loaded arrays if True.

• convert_parent (boolean (default = True)) – Propagate units change from a halo catalogue to a parent snapshot. See note below.

Note

The option convert_parent is only applicable to Halo objects. It is ignored by all other objects, including pynbody.snapshot.simsnap.SimSnap, pynbody.snapshot.subsnap.SubSnap, and pynbody.halo.HaloCatalogue objects.

When physical_units is called on a pynbody.halo.Halo and convert_parent is True, no immediate action is taken on the pynbody.halo.Halo itself; rather the request is passed upwards to the pynbody.halo.HaloCatalogue.

The catalogue object then calls physical_units on the parent snapshot and on all cached halos, setting convert_parent=False so that the units change is then applied to the pynbody.halo.Halo object itself.

This ensures that unit changes propagate through to properties of all halos. Most users will not need to worry about this subtlety; things should ‘just work’ if you ignore the convert_parent option.

precalculate()

Deprecated alias for load_all()