Velociraptor Python Library

Velociraptor catalogues provide a signifciant amount of information, but applying units to it can be painful. Here, the unyt python library is used to automatically apply units to velociraptor data and perform generic halo-catalogue reduction. This library is primarily intended to be used on SWIFT data that has been post-processed with velociraptor, but can be used for any velociraptor catalogue.

The internals of this library are based heavily on the internals of the swiftsimio library, and essentially allow the velociraptor catalogue to be accessed in a lazy, object-oriented way. This enables users to be able to reduce data quickly and in a computationally efficient manner, without having to resort to using the h5py library to manually load data (and hence manually apply units)!

Requirements

The velociraptor library requires:

unyt and its dependencies
h5py and its dependencies
python3.6 or above

Note that for development, we suggest that you have pytest and black installed. To create the plots in the example directory, you will need the plotting framework matplotlib.

Installation

You can install this library from PyPI using:

pip3 install velociraptor

Documentation

Full documentation is available on ReadTheDocs.

Why a custom library?

This custom library, instead of something like pandas, allows us to only load in the data that we require, and provide significant context-dependent features that would not be available for something generic. One example of this is the automatic labelling of properties, as shown in the below example.

from velociraptor import load
from velociraptor.tools import get_full_label

catalogue = load("/path/to/catalogue.properties")

stellar_masses = catalogue.apertures.mass_star_30_kpc
stellar_masses.convert_to_units("msun")

print(get_full_label(stellar_masses))

This outputs "Stellar Mass $M_*$ (30 kpc) $\left[M_\odot\right]$", which is easy to add as, for example, a label on a plot.

Metadata

Release files for velociraptor 0.21.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for velociraptor 0.21.1
File	Size	Uploaded
velociraptor-0.21.1.tar.gz	88.1 kB	Oct 9, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for velociraptor 0.21.1
File	Interpreter	ABI	Platform	Reset
velociraptor-0.21.1-py3-none-any.whl 99.3 kB Oct 9, 2026	Python 3	none	any	Details

Total release size: 187.4 kB

Release files / velociraptor-0.21.1.tar.gz

Download URL	velociraptor-0.21.1.tar.gz
Size	88.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`dfe28f14437f391a737b4c7e30aed9f74789683beb17e143fe8b35f4dfcb8aef`
BLAKE2b-256 checksum How to use checksums	`5081c7f58cc40325c8db226712c4fc9ca0d0b5ed54fb3d5eb8116616247ca3f4`
Upload date	Oct 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/SWIFTSIM/velociraptor-python
Publishing commit: github.com/SWIFTSIM/velociraptor-python/tree/3d74abb31ad6bd7a8d86bb3a52c5a1f9c0c3fb5e

Workflow

Publishing configuration: github.com/SWIFTSIM/velociraptor-python/blob/3d74abb31ad6bd7a8d86bb3a52c5a1f9c0c3fb5e/.github/workflows/python-publish.yml
Publishing logs: github.com/SWIFTSIM/velociraptor-python/actions/runs/37933435780/attempts/1

Artifact

Subject: velociraptor-0.21.1.tar.gz
SHA-256 checksum: dfe28f14437f391a737b4c7e30aed9f74789683beb17e143fe8b35f4dfcb8aef Verifying attestations

Release files / velociraptor-0.21.1-py3-none-any.whl

Download URL	velociraptor-0.21.1-py3-none-any.whl
Size	99.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`36ff472cba4efaf68108f4a544a13112e49298add17935ea6278d893b626db89`
BLAKE2b-256 checksum How to use checksums	`14f8be93baa618ef8a29d696ddafc726b86f60ea4bbcfa06743182a2c31a8645`
Upload date	Oct 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/SWIFTSIM/velociraptor-python
Publishing commit: github.com/SWIFTSIM/velociraptor-python/tree/3d74abb31ad6bd7a8d86bb3a52c5a1f9c0c3fb5e

Workflow

Publishing configuration: github.com/SWIFTSIM/velociraptor-python/blob/3d74abb31ad6bd7a8d86bb3a52c5a1f9c0c3fb5e/.github/workflows/python-publish.yml
Publishing logs: github.com/SWIFTSIM/velociraptor-python/actions/runs/37933435780/attempts/1

Artifact

Subject: velociraptor-0.21.1-py3-none-any.whl
SHA-256 checksum: 36ff472cba4efaf68108f4a544a13112e49298add17935ea6278d893b626db89 Verifying attestations