swiftgalaxy.reader module

This module contains wrappers for the parts making up a swiftsimio dataset to facilitate analyses of individual simulated galaxies.

The top-level wrapper is SWIFTGalaxy, which inherits from SWIFTDataset. It extends the functionality of a dataset to select particles belonging to a single galaxy, handle coordinate transformations while keeping all particles in a consistent frame of reference, providing spherical and cylindrical coordinates, and more.

Additional wrappers are provided for swiftsimio.reader.__SWIFTParticleDataset and swiftsimio.reader.__SWIFTNamedColumnDataset: _SWIFTParticleDatasetHelper and _SWIFTNamedColumnDatasetHelper, respectively. In general objects of these types should not be created directly by users, but rather by an object of the SWIFTGalaxy class.

class swiftgalaxy.reader.SWIFTGalaxy(snapshot_filename: str, halo_finder: _HaloFinder, auto_recentre: bool = True, transforms_like_coordinates: Set[str] = {}, transforms_like_velocities: Set[str] = {}, id_particle_dataset_name: str = 'particle_ids', coordinates_dataset_name: str = 'coordinates', velocities_dataset_name: str = 'velocities', coordinate_frame_from: SWIFTGalaxy | None = None, _spatial_mask: SWIFTMask | None = None, _extra_mask: MaskCollection | None = None, _coordinate_like_transform: ndarray | None = None, _velocity_like_transform: ndarray | None = None)[source]

Bases: SWIFTDataset

A representation of a simulated galaxy.

A SWIFTGalaxy represents a galaxy from a simulation, including both its particles and integrated properties. A halo finder catalogue is required to define which particles belong to the galaxy and to provide integrated properties. The implementation is an extension of the SWIFTDataset class, so all the functionality of such a dataset is also available for a SWIFTGalaxy. The swiftsimio.reader.__SWIFTParticleDataset objects familiar to swiftsimio users (e.g. a GasDataset) are wrapped by a _SWIFTParticleDatasetHelper class that exposes their usual functionality and extends it with new features. swiftsimio.reader.__SWIFTNamedColumnDataset instances are also wrapped, using a _SWIFTNamedColumnDatasetHelper class.

For an overview of available features see the examples below, and the narrative documentation pages.

Parameters:

  • snapshot_filename (str) – Name of file containing snapshot.

  • halo_finder (_HaloFinder) – A halo_finder instance from swiftgalaxy.halo_finders, e.g. a swiftgalaxy.halo_finders.Velociraptor instance.

  • auto_recentre (bool, default: True) – If True, the coordinate system will be automatically recentred on the position and velocity centres defined by the halo_finder.

  • transforms_like_coordinates (set [str], default: set()) – Names of fields that behave as spatial coordinates. It is assumed that these exist for all present particle types. When the coordinate system is rotated or translated, the associated arrays will be transformed accordingly. The coordinates dataset (or its alternative name given in the coordinates_dataset_name parameter) is implicitly assumed to behave as spatial coordinates.

  • transforms_like_velocities (set [str], default: set()) – Names of fields that behave as velocities. It is assumed that these exist for all present particle types. When the coordinate system is rotated or boosted, the associated arrays will be transformed accordingly. The velocities dataset (or its alternative name given in the velocities_dataset_name parameter) is implicitly assumed to behave as velocities.

  • id_particle_dataset_name (str, default: 'particle_ids') – Name of the dataset containing the particle IDs, assumed to be the same for all present particle types.

  • coordinates_dataset_name (str, default: 'velocities') – Name of the dataset containing the particle spatial coordinates, assumed to be the same for all present particle types.

  • velocities_dataset_name (str, default: 'velocities') – Name of the dataset containing the particle velocities, assumed to be the same for all present particle types.

See also

_SWIFTParticleDatasetHelper, _SWIFTNamedColumnDatasetHelper, swiftgalaxy.halo_finders

Examples

Assuming we have a snapshot file snap.hdf5, and velociraptor outputs halos.properties, halos.catalog_groups, etc., with the default names for coordinates, velocities and particle_ids, we can initialise a SWIFTGalaxy for the first row (indexed from 0) in the halo catalogue very easily:

from swiftgalaxy import SWIFTGalaxy, Velociraptor
mygalaxy = SWIFTGalaxy(
    'snap.hdf5',
    Velociraptor(
        'halos',
        halo_index=0
    )
)

Like a SWIFTDataset, the particle datasets are accessed as below, and all data are loaded ‘lazily’, on demand.

mygalaxy.gas.particle_ids
mygalaxy.dark_matter.coordinates

However, information from the halo finder is used to select only the particles identified as bound to this galaxy. The coordinate system is centred in both position and velocity on the centre and peculiar velocity of the galaxy, as determined by the halo finder. The coordinate system can be further manipulated, and all particle arrays will stay in a consistent reference frame at all times.

Again like for a SWIFTDataset, the units and metadata are available:

mygalaxy.units
mygalaxy.metadata

The halo finder interface is accessible as shown below. What this interface looks like depends on the halo finder being used, but will provide values for the individual galaxy of interest.

mygalaxy.halo_finder

In this case with Velociraptor, we can get the virial mass like this:

mygalaxy.halo_finder.masses.mvir

For a complete description of available features see the narrative documentation pages.

boost(boost: cosmo_array) → None[source]

Apply a ‘boost’ to the velocity coordinates.

The provided velocity vector is added to all particle velocities. If the ‘reference velocity’ that should be set to zero is known, use recentre_velocity() instead. All datasets specified in the transforms_like_velocities argument to SWIFTGalaxy are transformed (by default velocities for all present particle types).

Parameters:

boost (cosmo_array) – The velocity to boost by.

See also

recentre_velocity()

create_particle_datasets()

Creates particle datasets for whatever particle types and names are specified in metadata.particle_types.

These can then be accessed using their underscore names, e.g. gas.

get_metadata()

Loads the metadata from the SWIFT snapshot.

Ordinarily this happens automatically, but you can call this function again if you mess things up.

get_units()

Loads the units from the SWIFT snapshot.

Ordinarily this happens automatically, but you can call this function again if you mess things up.

mask_particles(mask_collection: MaskCollection) → None[source]

Select a subset of the currently selected particles.

The masks to be applied can by in any format accepted by a cosmo_array via __getitem__() and should be collected in a swiftgalaxy.masks.MaskCollection. The selection is applied permanently to all particle datasets for this galaxy. Temporary masks (e.g. for interactive use) can be created by using the __getitem__() (square brackets) method of the SWIFTGalaxy, any of its associated _SWIFTParticleDatasetHelper or _SWIFTNamedColumnDatasetHelper objects, but note that to ensure internal consistency, these return a masked copy of the entire SWIFTGalaxy, and are therefore relatively memory-intensive. Masking individual cosmo_array datasets with __getitem__() avoids this: only masked copies of the individual arrays are returned in this case.

Parameters:

mask_collection (swiftgalaxy.masks.MaskCollection) – Set of masks to be applied to each particle type. Particle types may be omitted by setting their mask to None, or simply omitting them from the swiftgalaxy.masks.MaskCollection.

recentre(new_centre: cosmo_array) → None[source]

Set a new centre for the particle spatial coordinates.

The provided (spatial) coordinate centre is set to zero by subtracting it from the particle coordinates. Note that this is the new centre in the current coordinate system (not e.g. the simulation box coordinates). If the coordinate offset to be applied is known, use translate() instead. All datasets specified in the transforms_like_coordinates argument to SWIFTGalaxy are transformed (by default coordinates for all present particle types).

Parameters:

new_centre (cosmo_array) – The new centre for the (spatial) coordinate system.

See also

translate()

recentre_velocity(new_centre: cosmo_array) → None[source]

Recentre the velocity coordinates.

The provided velocity coordinate is set to zero by subtracting it from the particle velocities. Note that this is the new velocity centre in the current coordinate system (not e.g. the simulation box coordinates). If the velocity offset to be applied is known, use boost() instead. All datasets specified in the transforms_like_velocities argument to SWIFTGalaxy are transformed (by default velocities for all present particle types).

Parameters:

new_centre (cosmo_array) – The new centre for the velocity coordinate system.

See also

boost()

rotate(rotation: Rotation) → None[source]

Apply a rotation to the particle spatial coordinates.

The provided rotation is applied to all particle coordinates. All datasets specified in the transforms_like_coordinates and transforms_like_velocities arguments to SWIFTGalaxy are transformed (by default coordinates and velocities for all present particle types).

Parameters:

rotation (scipy.spatial.transform.Rotation) – The rotation to be applied. Rotation supports several input formats, including axis-angle, rotation matrices, and others.

translate(translation: cosmo_array) → None[source]

Apply a translation to the particle spatial coordinates.

The provided translation vector is added to all particle coordinates. If the new centre position that should be set to zero is known, use recentre() instead. All datasets specified in the transforms_like_coordinates argument to SWIFTGalaxy are transformed (by default coordinates for all present particle types).

Parameters:

translation (cosmo_array) – The vector to translate by.

See also

recentre()

wrap_box() → None[source]

Wrap the particle coordinates in a periodic box.

Recentres a particle coordinates from a periodic simulation volume such that the coordinate (0, 0, 0) is in the centre and the axes of the volume are aligned with the coordinate axes.

Note

This is invoked automatically after any coordinate translations or rotations, so manually calling this function should usually not be necessary.

class swiftgalaxy.reader._CoordinateHelper(coordinates: dict | cosmo_array, masks: dict)[source]

Bases: object

Container class for coordinates.

Stores a dictionary of coordinate arrays and names (and aliases) for these, and enables accessing the arrays via __getattr__() (dot syntax). For interactive use, printing a _CoordinateHelper lists the available coordinate names and aliases.

Parameters:

  • coordinates (Union[dict, cosmo_array]) – The coordinate array(s) to be stored.

  • masks (dict) – Available coordinate names and their aliases with corresponding masks (or keys) into the coordinate array or dictionary for each.

class swiftgalaxy.reader._SWIFTNamedColumnDatasetHelper(named_column_dataset: __SWIFTNamedColumnDataset, particle_dataset_helper: _SWIFTParticleDatasetHelper)[source]

Bases: object

A wrapper class to enable SWIFTGalaxy functionality for a swiftsimio.reader.__SWIFTNamedColumnDataset.

Unlike the SWIFTGalaxy class that inherits directly from SWIFTDataset, for technical reasons this class does not inherit swiftsimio.reader.__SWIFTNamedColumnDataset. It does, however, expose the functionality of that class by maintaining an instance internally and forwarding any attribute lookups that it does not handle itself to its internal named column dataset.

Like _SWIFTParticleDatasetHelper, this class handles the transformation and masking of data from calls to SWIFTGalaxy routines.

Instances of this helper class should in general not be created separately since they require an instance of SWIFTGalaxy to function and will be created automatically by that class.

If any datasets contained in a named column dataset should transform like particle coordinates or velocities, these can be specified in the arguments transforms_like_coordinates and transforms_like_velocities to SWIFTGalaxy as a string containing a dot, e.g. the argument transforms_like_coordinates={'coordinates', 'extra_coordinates.an_extra_coordinate'} is syntactically valid.

Parameters:

See also

SWIFTGalaxy, _SWIFTParticleDatasetHelper

class swiftgalaxy.reader._SWIFTParticleDatasetHelper(particle_dataset: __SWIFTParticleDataset, swiftgalaxy: SWIFTGalaxy)[source]

Bases: object

A wrapper class to enable SWIFTGalaxy functionality for a swiftsimio.reader.__SWIFTParticleDataset.

Unlike the SWIFTGalaxy class that inherits directly from SWIFTDataset, for technical reasons this class does not inherit swiftsimio.reader.__SWIFTParticleDataset. It does, however, expose the functionality of that class by maintaining an instance internally and forwarding any attribute lookups that it does not handle itself to its internal particle dataset.

In addition to handling the transformation and masking of data from calls to SWIFTGalaxy routines, this class provides particle coordinates and velocities in cartesian, spherical and cylindrical coordinates through the properties:

These are evaluated lazily and automatically re-calculated if necessary, such as after a coordinate rotation.

Instances of this helper class should in general not be created separately since they require an instance of SWIFTGalaxy to function and will be created automatically by that class.

Parameters:

  • particle_dataset (swiftsimio.reader.__SWIFTParticleDataset) – The particle dataset to be wrapped.

  • swiftgalaxy (SWIFTGalaxy) – Used to store a reference to the parent SWIFTGalaxy.

See also

SWIFTGalaxy, _CoordinateHelper

Examples

The cartesian, spherical and cylindrical coordinates of gas particles can be accessed, for example, by (mygalaxy is a SWIFTGalaxy):

mygalaxy.gas.cartesian_coordinates.x
mygalaxy.gas.cartesian_coordinates.y
mygalaxy.gas.cartesian_coordinates.z
mygalaxy.gas.cartesian_velocities.x
mygalaxy.gas.cartesian_velocities.y
mygalaxy.gas.cartesian_velocities.z
mygalaxy.gas.spherical_coordinates.r
mygalaxy.gas.spherical_coordinates.theta
mygalaxy.gas.spherical_coordinates.phi
mygalaxy.gas.spherical_velocities.r
mygalaxy.gas.spherical_velocities.theta
mygalaxy.gas.spherical_velocities.phi
mygalaxy.gas.cylindrical_coordinates.rho
mygalaxy.gas.cylindrical_coordinates.phi
mygalaxy.gas.cylindrical_coordinates.z
mygalaxy.gas.cylindrical_velocities.rho
mygalaxy.gas.cylindrical_velocities.phi
mygalaxy.gas.cylindrical_velocities.z
property cartesian_coordinates: _CoordinateHelper

Utility to access the cartesian coordinates of particles.

Returns a wrapper around the coordinate array which can be accessed using attribute syntax. Cartesian coordinates can be accessed separately:

  • cartesian_coordinates.x

  • cartesian_coordinates.y

  • cartesian_coordinates.z

or as a 2D array:

  • cartesian_coordinates.xyz

A reference to the coordinates array is obtained each time, so cartesian coordinates are automatically updated if the coordinates array is modified (e.g. following a rotation or other transformation).

By default the coorinate array is assumed to be called coordinates, but this can be overridden with the coordinates_dataset_name argument to SWIFTGalaxy.

Returns:

coordinate_helper – Container providing particle cartesian coordinates as attributes.

Return type:

_CoordinateHelper

property cartesian_velocities: _CoordinateHelper

Utility to access the cartesian components of particle velocities.

Returns a wrapper around the velocities array which can be accessed using attribute syntax. Cartesian coordinates can be accessed separately:

  • cartesian_velocities.x

  • cartesian_velocities.y

  • cartesian_velocities.z

or as a 2D array:

  • cartesian_velocities.xyz

A reference to the velocities array is obtained each time, so cartesian velocities are automatically updated if the velocities array is modified (e.g. following a rotation or other transformation).

By default the array of velocities is assumed to be called velocities, but this can be overridden with the velocities_dataset_name argument to SWIFTGalaxy.

Returns:

coordinate_helper – Container providing particle cartesian velocities as attributes.

Return type:

_CoordinateHelper

property cylindrical_coordinates: _CoordinateHelper

Utility to access the cylindrical coordinates of particles.

The cylindrical coordinates of particles are calculated the first time this attribute is accessed. If a coordinate transformation (e.g. a rotation) or other operation is applied to the SWIFTGalaxy that would invalidate the derived cylindrical coordinates, they are erased and will be recalculated at the next access of this attribute. The coordinates could be transformed when they change instead, but in general this requires transforming back through cartesian coordinates, so the more efficient “lazy” approach of recalculating on demand is used instead.

The coordinate components are named \((\rho, \phi, z)\) by default, and assume a convention where \(0 < \phi \leq 2\pi\).

Several attribute names are supported for each coordinate. They can be accessed with the aliases:

  • cylindrical_coordinates.rho:

    • cylindrical_coordinates.R

    • cylindrical_coordinates.radius

  • cylindrical_coordinates.phi:

    • cylindrical_coordinates.lon

    • cylindrical_coordinates.longitude

    • cylindrical_coordinates.az

    • cylindrical_coordinates.azimuth

  • cylindrical_coordinates.z

By default the coorinate array is assumed to be called coordinates, but this can be overridden with the coordinates_dataset_name argument to SWIFTGalaxy.

Returns:

coordinate_helper – Container providing particle cylindrical coordinates as attributes.

Return type:

_CoordinateHelper

property cylindrical_velocities: _CoordinateHelper

Utility to access the velocities of particles in cylindrical coordinates.

The particle velocities in cylindrical coordinates are calculated the first time this attribute is accessed. If a coordinate transformation (e.g. a rotation) or other operation is applied to the SWIFTGalaxy that would invalidate the derived cylindrical velocities, they are erased and will be recalculated at the next access of this attribute. The velocities could be transformed when they change instead, but in general this requires transforming back through cartesian coordinates, so the more efficient “lazy” approach of recalculating on demand is used instead.

The “physics” notation convention, where \(-\frac{\pi}{2} \leq \theta \leq \frac{\pi}{2}\) is the polar angle and \(0 < \phi \leq 2\pi\) is the azimuthal angle, is assumed.

The coordinate components are named \((\rho, \phi, z)\) by default, and assume a convention where \(0 < \phi \leq 2\pi\).

Several attribute names are supported for each velocity component. They can be accessed with the aliases:

  • cylindrical_velocities.rho:

    • cylindrical_velocities.R

    • cylindrical_velocities.radius

  • cylindrical_coordinates.phi:

    • cylindrical_velocities.lon

    • cylindrical_velocities.longitude

    • cylindrical_velocities.az

    • cylindrical_velocities.azimuth

  • cylindrical_velocities.z

By default the array of velocities is assumed to be called velocities, but this can be overridden with the velocities_dataset_name argument to SWIFTGalaxy.

Returns:

coordinate_helper – Container providing particle velocities in cylindrical coordinates as attributes.

Return type:

_CoordinateHelper

property spherical_coordinates: _CoordinateHelper

Utility to access the spherical coordinates of particles.

The spherical coordinates of particles are calculated the first time this attribute is accessed. If a coordinate transformation (e.g. a rotation) or other operation is applied to the SWIFTGalaxy that would invalidate the derived spherical coordinates, they are erased and will be recalculated at the next access of this attribute. The coordinates could be transformed when they change instead, but in general this requires transforming back through cartesian coordinates, so the more efficient “lazy” approach of recalculating on demand is used instead.

The “physics” notation convention, where \(-\frac{\pi}{2} \leq \theta \leq \frac{\pi}{2}\) is the polar angle and \(0 < \phi \leq 2\pi\) is the azimuthal angle, is assumed.

Several attribute names are supported for each coordinate. They can be accessed with the aliases:

  • spherical_coordinates.r:

    • spherical_coordinates.radius

  • spherical_coordinates.theta:

    • spherical_coordinates.lat

    • spherical_coordinates.latitude

    • spherical_coordinates.pol

    • spherical_coordinates.polar

  • spherical_coordinates.phi:

    • spherical_coordinates.lon

    • spherical_coordinates.longitude

    • spherical_coordinates.az

    • spherical_coordinates.azimuth

By default the coorinate array is assumed to be called coordinates, but this can be overridden with the coordinates_dataset_name argument to SWIFTGalaxy.

Returns:

coordinate_helper – Container providing particle spherical coordinates as attributes.

Return type:

_CoordinateHelper

property spherical_velocities: _CoordinateHelper

Utility to access the velocities of particles in spherical coordinates.

The particle velocities in spherical coordinates are calculated the first time this attribute is accessed. If a coordinate transformation (e.g. a rotation) or other operation is applied to the SWIFTGalaxy that would invalidate the derived spherical velocities, they are erased and will be recalculated at the next access of this attribute. The velocities could be transformed when they change instead, but in general this requires transforming back through cartesian coordinates, so the more efficient “lazy” approach of recalculating on demand is used instead.

The “physics” notation convention, where \(-\frac{\pi}{2} \leq \theta \leq \frac{\pi}{2}\) is the polar angle and \(0 < \phi \leq 2\pi\) is the azimuthal angle, is assumed.

Several attribute names are supported for each velocity component. They can be accessed with the aliases:

  • spherical_velocities.r:

    • spherical_velocities.radius

  • spherical_velocities.theta:

    • spherical_velocities.lat

    • spherical_velocities.latitude

    • spherical_velocities.pol

    • spherical_velocities.polar

  • spherical_velocities.phi:

    • spherical_velocities.lon

    • spherical_velocities.longitude

    • spherical_velocities.az

    • spherical_velocities.azimuth

By default the array of velocities is assumed to be called velocities, but this can be overridden with the velocities_dataset_name argument to SWIFTGalaxy.

Returns:

coordinate_helper – Container providing particle velocities in spherical coordinates as attributes.

Return type:

_CoordinateHelper