swiftgalaxy.halo_finders module

This module contains classes providing interfaces to halo finders used with SWIFT so that swiftgalaxy can obtain the information it requires in a streamlined way. Currently only the Velociraptor halo finder is supported, but support for other halo finders (e.g. SOAP, HBT+) is planned.

class swiftgalaxy.halo_finders.Caesar(caesar_file: str | None = None, group_type: str | None = None, group_index: int | None = None, centre_type: str = 'minpot', extra_mask: str | MaskCollection = 'bound_only', custom_spatial_offsets: cosmo_array | None = None)[source]

Bases: _HaloFinder

Interface to Caesar halo catalogues for use with swiftgalaxy.

Takes a caesar output file and configuration options and provides an interface that swiftgalaxy understands. Also exposes the halo/galaxy properties computed by CAESAR for a single object of interest with the same interface provided by the Group class in the caesar python package. Reading of properties is done on-the-fly, and only rows corresponding to the object of interest are read from disk.

Parameters:

  • caesar_file (str) – The catalogue file (hdf5 format) output by caesar.

  • group_type (str) – The category of the object of interest, either "halo" or "galaxy".

  • group_index (int) – Position of the object of interest in the catalogue arrays.

  • extra_mask (Union[str, MaskCollection], default: "bound_only") – Mask to apply to particles after spatial masking. If "bound_only", then the galaxy is masked to include only the gravitationally bound particles as provided by caesar. A user-defined mask can also be as an an object (such as a swiftgalaxy.masks.MaskCollection) that has attributes with names corresponding to present particle names (e.g. gas, dark_matter, etc.), each containing a mask.

  • centre_type (str, default: "minpot") – Type of centre, chosen from those provided by caesar. Default is the position of the particle with the minimum potential, "minpot", alternatively "" can be used for the centre of mass.

  • custom_spatial_offsets (Optional[cosmo_array], default: None) – A region to override the automatically-determined region enclosing group member particles. May be used in conjunction with extra_mask, for example to select all simulation particles in an aperture around the object of interest (see ‘Masking’ section of documentation for a cookbook example). Provide a pair of offsets from the object’s centre along each axis to define the region, for example for a cube extending +/- 1 Mpc from the centre: cosmo_array([[-1.0, 1.0], [-1.0, 1.0], [-1.0, 1.0]], u.Mpc).

Notes

Note

loader.CAESAR only supports index access to catalogue lists, not identifier access. This means that the group_index is simply the position of the object of interest in the catalogue list.

Examples

Given a file s12.5n128_0012.hdf5 at /output/path/, the following creates a Caesar object for the entry at index 3 in the catalogue (i.e. the 4th row, indexed from 0) and demonstrates retrieving its virial mass.

>>> cat = Caesar(
>>>     caesar_file="/output/path/s12.5n128_0012.hdf5",
>>>     group_type="halo",
>>>     group_index=3,  # 4th entry in catalogue (indexed from 0)
>>> )
>>> cat.info()
{'GroupID': 3,
'ages': {'mass_weighted': unyt_quantity(2.26558173, 'Gyr'),
         'metal_weighted': unyt_quantity(2.21677032, 'Gyr')},
'bh_fedd': unyt_quantity(3.97765937, 'dimensionless'),
'bhlist_end': 12,
'bhlist_start': 11,
...
'virial_quantities': {'circular_velocity': unyt_quantity(158.330253, 'km/s'),
                      'm200c': unyt_quantity(1.46414384e+12, 'Msun'),
                      'm2500c': unyt_quantity(8.72801239e+11, 'Msun'),
                      'm500c': unyt_quantity(1.23571772e+12, 'Msun'),
                      'r200': unyt_quantity(425.10320408, 'kpccm'),
                      'r200c': unyt_quantity(327.46600342, 'kpccm'),
                      'r2500c': unyt_quantity(118.77589417, 'kpccm'),
                      'r500c': unyt_quantity(228.03265381, 'kpccm'),
                      'spin_param': unyt_quantity(2.28429179,'s/(Msun*km*kpccm)'),
                      'temperature': unyt_quantity(902464.88453405, 'K')}}
>>> cat.virial_quantities
{'circular_velocity': unyt_quantity(158.330253, 'km/s'),
 'm200c': unyt_quantity(1.46414384e+12, 'Msun'),
 'm2500c': unyt_quantity(8.72801239e+11, 'Msun'),
 'm500c': unyt_quantity(1.23571772e+12, 'Msun'),
 'r200': unyt_quantity(425.10320408, 'kpccm'),
 'r200c': unyt_quantity(327.46600342, 'kpccm'),
 'r2500c': unyt_quantity(118.77589417, 'kpccm'),
 'r500c': unyt_quantity(228.03265381, 'kpccm'),
 'spin_param': unyt_quantity(2.28429179, 's/(Msun*km*kpccm)'),
 'temperature': unyt_quantity(902464.88453405, 'K')}
>>> cat.virial_quantities["m200c"]
unyt_quantity(1.46414384e+12, 'Msun')
property centre: cosmo_array

Obtain the centre specified by the centre_type from the halo catalogue.

Returns:

centre – The centre provided by the halo catalogue.

Return type:

cosmo_array

property velocity_centre: cosmo_array

Obtain the velocity centre specified by the centre_type from the halo catalogue.

Returns:

velocity_centre – The velocity centre provided by the halo catalogue.

Return type:

cosmo_array

class swiftgalaxy.halo_finders.Standalone(centre: cosmo_array | None = None, velocity_centre: cosmo_array | None = None, spatial_offsets: cosmo_array | None = None, extra_mask: str | MaskCollection | None = None)[source]

Bases: _HaloFinder

A bare-bones tool to initialize a SWIFTGalaxy without an associated halo catalogue.

Provides an interface to specify the minimum required information to instantiate a SWIFTGalaxy.

Parameters:

  • centre (Optional[cosmo_array], default: None) – A value for this parameter is required, and must have units of length. Specifies the geometric centre in simulation coordinates. Particle coordinates will be shifted such that this position is located at (0, 0, 0) and if the boundary is periodic it will be wrapped to place the origin at the centre.

  • velocity_centre (Optional[cosmo_array], default: None) – A value for this parameter is required, and must have units of speed. Specifies the reference velocity relative to the simulation frame. Particle velocities will be shifted such that a particle with the specified velocity in the simulation frame will have zero velocity in the SWIFTGalaxy frame.

  • spatial_offsets (Optional[cosmo_array], default: None) – Offsets along each axis to select a spatial region around the centre. May be used in conjunction with extra_mask, for example to select all simulation particles in an aperture around the object of interest (see ‘Masking’ section of documentation for a cookbook example). Provide a pair of offsets from the object’s centre along each axis to define the region, for example for a cube extending +/- 1 Mpc from the centre: cosmo_array([[-1.0, 1.0], [-1.0, 1.0], [-1.0, 1.0]], u.Mpc).

  • extra_mask (Optional[Union[str, MaskCollection]], default: None) – Mask to apply to particles after spatial masking. A user-defined mask can be provided as an an object (such as a swiftgalaxy.masks.MaskCollection) that has attributes with names corresponding to present particle names (e.g. gas, dark_matter, etc.), each containing a mask.

Examples

Often the most pragmatic way to create a selection of particles using Standalone is to first select a spatial region guaranteed to contain the particles of interest and then create the final mask programatically using SWIFTGalaxy’s masking features. For example, suppose we know that there is a galaxy with its centre at (2, 2, 2) Mpc and we eventually want all particles in a spherical aperture 1 Mpc in radius around this point. We start with a cubic spatial mask enclosing this region:

from swiftgalaxy import SWIFTGalaxy, Standalone, MaskCollection
from swiftsimio import cosmo_array
import unyt as u

sg = SWIFTGalaxy(
    "my_snapshot.hdf5",
    Standalone(
        centre=cosmo_array([2.0, 2.0, 2.0], u.Mpc),
        velocity_centre=cosmo_array([0.0, 0.0, 0.0], u.km / u.s),
        spatial_offsets=cosmo_array(
            [[-1.0, 1.0], [-1.0, 1.0], [-1.0, 1.0]],
            u.Mpc,
        ),
        extra_mask=None,  # we'll define the exact set of particles later
    )
)

We next define the masks selecting particles in the desired spherical aperture, conveniently using SWIFTGalaxy’s spherical coordinates feature, and store them in a MaskCollection:

mask_collection = MaskCollection(
    gas=sg.gas.spherical_coordinates.r < 1 * u.Mpc,
    dark_matter=sg.dark_matter.spherical_coordinates.r < 1 * u.Mpc,
    stars=sg.stars.spherical_coordinates.r < 1 * u.Mpc,
    black_holes=sg.black_holes.spherical_coordinates.r < 1 * u.Mpc,
)

Finally, we apply the mask to the sg object:

sg = sg.mask_particles(mask_collection)

We’re now ready to proceed with analysis of the particles in the 1 Mpc spherical aperture using this sg object.

Note

mask_particles() applies the masks in-place. The mask could also be applied with the __getattr__() method (i.e. in square brackets), but this returns a copy of the SWIFTGalaxy object. If memory efficiency is a concern, prefer the mask_particles() approach.

property centre: cosmo_array

Obtain the centre specified at initialisation.

property velocity_centre: cosmo_array

Obtain the velocity centre specified at initialisation.

class swiftgalaxy.halo_finders.Velociraptor(velociraptor_filebase: str | None = None, velociraptor_files: dict | None = None, halo_index: int | None = None, extra_mask: str | MaskCollection = 'bound_only', centre_type: str = 'minpot', velociraptor_suffix: str = '', custom_spatial_offsets: cosmo_array | None = None)[source]

Bases: _HaloFinder

Interface to velociraptor halo catalogues for use with swiftgalaxy.

Takes a set of velociraptor output files and configuration options and provides an interface that swiftgalaxy understands. Also exposes the halo/galaxy properties computed by velociraptor for a single object of interest with the API provided by the velociraptor python package. Reading of properties is done on-the-fly, and only rows corresponding to the object of interest are read from disk.

Parameters:

  • velociraptor_filebase (str) – The initial part of the velociraptor filenames (possibly including path), e.g. if there is a halos.properties file, pass halos as this argument. Provide this or velociraptor_files, not both.

  • velociraptor_files (dict[str]) – A dictionary containing the names of the velociraptor files (possibly including paths). There should be two entries, with keys properties and catalog_groups containing locations of the {halos}.properties and {halos}.catalog_groups files, respectively. Provide this or velociraptor_filebase, not both.

  • halo_index (int) – Position of the object of interest in the catalogue arrays.

  • extra_mask (Union[str, MaskCollection], default: "bound_only") – Mask to apply to particles after spatial masking. If "bound_only", then the galaxy is masked to include only the gravitationally bound particles as determined by velociraptor. A user-defined mask can also be provided as an an object (such as a swiftgalaxy.masks.MaskCollection) that has attributes with names corresponding to present particle names (e.g. gas, dark_matter, etc.), each containing a mask.

  • centre_type (str, default: "minpot") – Type of centre, chosen from those provided by velociraptor. Default is the position of the particle with the minimum potential, "minpot"; other possibilities may include "", "_gas", "_star", "mbp" (most bound particle).

  • custom_spatial_offsets (Optional[cosmo_array], default: None) – A region to override the automatically-determined region enclosing group member particles. May be used in conjunction with extra_mask, for example to select all simulation particles in an aperture around the object of interest (see ‘Masking’ section of documentation for a cookbook example). Provide a pair of offsets from the object’s centre along each axis to define the region, for example for a cube extending +/- 1 Mpc from the centre: cosmo_array([[-1.0, 1.0], [-1.0, 1.0], [-1.0, 1.0]], u.Mpc).

Notes

Note

velociraptor only supports index access to catalogue arrays, not identifier access. This means that the halo_index is simply the position of the object of interest in the catalogue arrays.

Examples

Given a file halos.properties (and also halos.catalog_groups, etc.) at /output/path/, the following creates a Velociraptor object for the entry at index 3 in the catalogue (i.e. the 4th row, indexed from 0) and demonstrates retrieving its virial mass.

>>> cat = Velociraptor(
>>>     velociraptor_filebase="/output/path/halos",  # halos.properties file is at
>>>                                                  # /output/path/
>>>     halo_index=3,  # 4th entry in catalogue (indexed from 0)
>>> )
>>> cat
Masked velociraptor catalogue at /path/to/output/out.properties.
Contains the following field collections: metallicity, ids, energies,
stellar_age, spherical_overdensities, rotational_support,
star_formation_rate, masses, eigenvectors, radii, temperature, veldisp,
structure_type, velocities, positions, concentration, rvmax_quantities,
angular_momentum, projected_apertures, apertures,
element_mass_fractions, dust_mass_fractions, number,
hydrogen_phase_fractions, black_hole_masses, stellar_birth_densities,
snii_thermal_feedback_densities, species_fractions,
gas_hydrogen_species_masses, gas_H_and_He_masses,
gas_diffuse_element_masses, dust_masses_from_table, dust_masses,
stellar_luminosities, cold_dense_gas_properties,
log_element_ratios_times_masses, lin_element_ratios_times_masses,
element_masses_in_stars, fail_all
>>> cat.masses
Contains the following fields: mass_200crit, mass_200crit_excl,
mass_200crit_excl_gas, mass_200crit_excl_gas_nsf,
mass_200crit_excl_gas_sf, mass_200crit_excl_star, mass_200crit_gas,
mass_200crit_gas_nsf, mass_200crit_gas_sf, mass_200crit_star,
mass_200mean, mass_200mean_excl, mass_200mean_excl_gas,
mass_200mean_excl_gas_nsf, mass_200mean_excl_gas_sf,
mass_200mean_excl_star, mass_200mean_gas, mass_200mean_gas_nsf,
mass_200mean_gas_sf, mass_200mean_star, mass_bn98, mass_bn98_excl,
mass_bn98_excl_gas, mass_bn98_excl_gas_nsf, mass_bn98_excl_gas_sf,
mass_bn98_excl_star, mass_bn98_gas, mass_bn98_gas_nsf,
mass_bn98_gas_sf, mass_bn98_star, mass_fof, mass_bh, mass_gas,
mass_gas_30kpc, mass_gas_500c, mass_gas_rvmax, mass_gas_hight_excl,
mass_gas_hight_incl, mass_gas_incl, mass_gas_nsf, mass_gas_nsf_incl,
mass_gas_sf, mass_gas_sf_incl, mass_star, mass_star_30kpc,
mass_star_500c, mass_star_rvmax, mass_star_incl, mass_tot,
mass_tot_incl, mvir
>>> cat.masses.mvir
unyt_array(14.73875777, '10000000000.0*Msun')
property centre: cosmo_array

Obtain the centre specified by the centre_type from the halo catalogue.

Returns:

centre – The centre provided by the halo catalogue.

Return type:

cosmo_array

property velocity_centre: cosmo_array

Obtain the velocity centre specified by the centre_type from the halo catalogue.

Returns:

velocity_centre – The velocity centre provided by the halo catalogue.

Return type:

cosmo_array