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 thatswiftgalaxy
understands. Also exposes the halo/galaxy properties computed by CAESAR for a single object of interest with the same interface provided by theGroup
class in thecaesar
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 bycaesar
. A user-defined mask can also be as an an object (such as aswiftgalaxy.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 bycaesar
. 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 withextra_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 thegroup_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 aCaesar
object for the entry at index3
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:
- 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:
- 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 theSWIFTGalaxy
frame.spatial_offsets (
Optional[cosmo_array]
, default:None
) – Offsets along each axis to select a spatial region around thecentre
. May be used in conjunction withextra_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 aswiftgalaxy.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 usingSWIFTGalaxy
’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 aMaskCollection
: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 theSWIFTGalaxy
object. If memory efficiency is a concern, prefer themask_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 thatswiftgalaxy
understands. Also exposes the halo/galaxy properties computed byvelociraptor
for a single object of interest with the API provided by thevelociraptor
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 ahalos.properties
file, passhalos
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 byvelociraptor
. A user-defined mask can also be provided as an an object (such as aswiftgalaxy.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 byvelociraptor
. 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 withextra_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 thehalo_index
is simply the position of the object of interest in the catalogue arrays.Examples
Given a file
halos.properties
(and alsohalos.catalog_groups
, etc.) at/output/path/
, the following creates aVelociraptor
object for the entry at index3
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:
- 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: