swiftgalaxy.halo_catalogues module

Provide a common interface to halo catalogues of different types.

This module contains classes providing interfaces to halo catalogues used with SWIFT so that swiftgalaxy can obtain the information it requires in a streamlined way. Currently SOAP and Velociraptor halo catalogues are supported, as well as Caesar catalogues, others can be supported on request.

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

Bases: _HaloCatalogue

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(s) of the object(s) of interest in the catalogue arrays. In the case of multiple objects, duplicate entries are not allowed.

  • centre_type (str (optional), 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.

  • extra_mask (str or MaskCollection (optional), 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.

  • custom_spatial_offsets (cosmo_array (optional), 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

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.

In multi-galaxy mode if no mask is active return the centres of all objects of interest, otherwise return the centre of the (current) object of interest.

Returns:

The centre(s) of the object(s) of interest.

Return type:

cosmo_array

property group_index: List[int] | int

Get the index of the object of interest in the halo catalogue.

In multi-galaxy mode when no mask is active this gets the list of indices. This is just the position in the arrays stored in the Caesar halo or galaxy lists (according to the group_type given at initialization).

Returns:

The index or indices of the object(s) of interest in the halo catalogue.

Return type:

int or list

property velocity_centre: cosmo_array

Obtain the velocity centre from the halo catalogue.

It is specified by the velocity_centre_type.

Returns:

The velocity centre provided by the halo catalogue.

Return type:

cosmo_array

class swiftgalaxy.halo_catalogues.SOAP(soap_file: str | None = None, soap_index: int | Sequence[int] | None = None, extra_mask: str | MaskCollection = 'bound_only', centre_type: str = 'input_halos.halo_centre', velocity_centre_type: str = 'bound_subhalo.centre_of_mass_velocity', custom_spatial_offsets: cosmo_array | None = None)[source]

Bases: _HaloCatalogue

Interface to SOAP halo catalogues for use with swiftgalaxy.

Takes a set of SOAP output files and configuration options and provides an interface that swiftgalaxy understands. Also exposes the galaxy properties computed by SOAP for a single object of interest through the swiftsimio interface.

Parameters:

  • soap_file (str, default: None) – The filename of a SOAP catalogue file, possibly including the path.

  • soap_index (int or list, default: None) – The position (row) in the SOAP catalogue corresponding to the object of interest. Duplicate entries are not allowed.

  • extra_mask (str or MaskCollection (optional), 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 SOAP. 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 (optional), default: "input_halos.halo_centre") – Type of centre, chosen from those provided by SOAP. This should be expressed as a string analogous to what would be written in swiftsimio code (or swiftgalaxy) to access that property in the SOAP catalogue. The default takes the "input_halos.halo_centre" (usually the centre of potential, e.g. the HBT+ halo finder defines it in this way; another option amongst many more is "bound_subhalo.centre_of_mass".

  • velocity_centre_type (str (optional), default: "bound_subhalo.centre_of_mass_velocity") – Type of velocity centre, chosen from those provided by SOAP. This should be expressed as a string analogous to what would be written in swiftsimio code (or swiftgalaxy) to access that property in the SOAP catalogue. The default takes the "bound_subhalo.centre_of_mass_velocity"; note that there is no velocity corresponding to the centre of potential ("input_halos.halo_centre_velocity" is not defined). Another useful option could be "exclusive_sphere_1kpc.centre_of_mass_velocity" to choose the velocity of bound particles in the central 1 kpc.

  • custom_spatial_offsets – 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

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

Examples

Given a file halo_properties_0050.hdf5, the following creates a SOAP object for the entry at index 0 in the catalogue (i.e. the 1st row, indexed from 0) and demonstrates retrieving its virial mass (M200crit).

>>> cat = SOAP(
>>>     soap_file="/output/path/halo_properties_0050.hdf5"
>>>     soap_index=0,  # 1st entry in catalogue (indexed from 0)
>>> )
>>> cat.spherical_overdensity_200_crit.total_mass.to(u.Msun)
cosmo_array([6.72e+12], dtype=float32, units='1.98841586e+30*kg', comoving=False)
property centre: cosmo_array

Obtain the centre from the halo catalogue.

It is specified by the centre_type.

In multi-galaxy mode if no mask is active return the centres of all objects of interest, otherwise return the centre of the (current) object of interest.

Returns:

The centre(s) of the object(s) of interest.

Return type:

cosmo_array

property soap_index: int | List[int]

Get the index of the objects of interest in the halo catalogue.

In multi-galaxy mode when no mask is active this gets the list of indices.

This is just the position in the arrays stored in the SOAP SWIFTDataset (that could have a SWIFTMask).

Returns:

The index or indices of the object(s) of interest in the halo catalogue.

Return type:

int or list

property velocity_centre: cosmo_array

Obtain the velocity centre from the halo catalogue.

It is specified by the velocity_centre_type.

In multi-galaxy mode if no mask is active return the centres of all objects of interest, otherwise return the centre of the (current) object of interest.

Returns:

The centre(s) of the object(s) of interest.

Return type:

cosmo_array

class swiftgalaxy.halo_catalogues.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: _HaloCatalogue

Use to initialize a SWIFTGalaxy without a halo catalogue.

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

Parameters:

  • centre (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 (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 (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 (str or MaskCollection (optional), 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 initialization.

In multi-galaxy mode if no mask is active return the centres of all objects of interest, otherwise return the centre of the (current) object of interest.

Returns:

The centre(s) of the object(s) of interest.

Return type:

cosmo_array

property velocity_centre: cosmo_array

Obtain the velocity centre specified at initialization.

In multi-galaxy mode if no mask is active return the centres of all objects of interest, otherwise return the centre of the (current) object of interest.

Returns:

The velocity coordinate origin.

Return type:

cosmo_array

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

Bases: _HaloCatalogue

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) – 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 or list) – Position(s) of the object(s) of interest in the catalogue arrays. In the case of multiple objects, duplicate entries are not allowed.

  • extra_mask (str or MaskCollection (optional), 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 (optional), 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 (~swiftsimio.objects.cosmo_array (optional), 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.

In multi-galaxy mode if no mask is active return the centres of all objects of interest, otherwise return the centre of the (current) object of interest.

Returns:

The centre(s) of the object(s) of interest.

Return type:

cosmo_array

property halo_index: List[int] | int

Get the index of the objects of interest in the halo catalogue.

In multi-galaxy mode when no mask is active this gets the list of indices.

This is just the position in the arrays stored in the Velociraptor catalogue files.

Returns:

The index or indices of the object(s) of interest in the halo catalogue.

Return type:

int or list

property velocity_centre: cosmo_array

Obtain the velocity centre from the halo catalogue.

Specified by the velocity_centre_type.

In multi-galaxy mode if no mask is active return the centres of all objects of interest, otherwise return the centre of the (current) object of interest.

Returns:

The centre(s) of the object(s) of interest.

Return type:

cosmo_array