swiftgalaxy

Python Version from PEP 621 TOML

SWIFTGalaxy is an open-source astrophysics module that extends SWIFTSimIO tailored to analyses of particles belonging to individual galaxies simulated with SWIFT. It inherits from and extends the functionality of the SWIFTDataset. It understands the content of halo catalogues (supported: Velociraptor, Caesar, SOAP) and therefore which particles belong to a galaxy or other group of particles, and its integrated properties. The particles occupy a coordinate frame that is enforced to be consistent, such that particles loaded on-the-fly will match e.g. rotations and translations of particles already in memory. Intuitive masking of particle datasets is also enabled. Utilities to make working in cylindrical and spherical coordinate systems more convenient are also provided. Finally, tools to iterate efficiently over multiple galaxies are also provided.

Installation is as simple as pip install swiftgalaxy.

To install optional dependencies to support Velociraptor catalogues use pip install swiftgalaxy[velociraptor]. For Caesar support use:

pip install git+https://github.com/dnarayanan/caesar.git

No additional dependencies are needed for reading SOAP catalogues. If you want to generate example input files for SOAP, you should install:

pip install git+https://github.com/SWIFTSIM/soap.git

Once installed, creating a SWIFTGalaxy object to get started with analysis is simple! For instance, for a SWIFT simulation with a SOAP-format halo catalogue (an example - 300 MB - will be automatically downloaded):

from swiftgalaxy import SWIFTGalaxy, SOAP
from swiftgalaxy.demo_data import web_examples

sg = SWIFTGalaxy(
    web_examples.virtual_snapshot,
    SOAP(web_examples.soap, soap_index=0)
)

# access data for particles belonging to the galaxy:
sg.gas.temperatures

# access integrated properties from the halo catalogue
sg.halo_catalogue.spherical_overdensity_200_crit.soradius

# automatically generated spherical/cylindrical coordinates:
sg.gas.spherical_coordinates.r

# consistent coordinate transformations of all particles, even those not loaded yet:
from scipy.spatial.transform import Rotation
sg.rotate(Rotation.from_euler("x", 90, degrees=True))

# compatible with swiftsimio visualisation:
import numpy as np
import unyt as u
from swiftsimio import cosmo_array
from swiftsimio.visualisation import project_gas
import matplotlib.pyplot as plt
img = project_gas(
    sg,
    periodic=False,
    resolution=256,
    region=cosmo_array(
        [-30, 30, -30, 30],
        u.kpc,
        comoving=True,
        scale_factor=sg.metadata.a,
        scale_exponent=1
    ),
)
plt.imsave("eagle6_galaxy.png", np.log10(img.T), origin="lower", cmap="inferno")

https://github.com/SWIFTSIM/swiftgalaxy/raw/main/eagle6_galaxy.png

Examples

More usage examples can be found in the examples folder on github.

Citing SWIFTGalaxy

If your use of SWIFTGalaxy leads to a publication, please cite the JOSS paper (ADS listing). You may also cite the swiftgalaxy entry in the ASCL (indexed on ADS). Ideally specify the version used (Zenodo DOI, git commit ID and/or version number) and link to the github repository.

@ARTICLE{2025JOSS...10.9278O,
    author = {{Oman}, Kyle A.},
    title = "{SWIFTGalaxy: a Python package to work with particle groups from SWIFT simulations}",
    journal = {The Journal of Open Source Software},
    keywords = {astronomy, simulations},
    year = 2025,
    month = oct,
    volume = {10},
    number = {114},
    eid = {9278},
    pages = {9278},
    doi = {10.21105/joss.09278},
    adsurl = {https://ui.adsabs.harvard.edu/abs/2025JOSS...10.9278O},
    adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}

@MISC{
    2025ascl.soft05002O,
    author = {{Oman}, Kyle A.},
    title = "{swiftgalaxy}",
    keywords = {Software},
    howpublished = {Astrophysics Source Code Library, record ascl:2505.002},
    year = 2025,
    month = may,
    eid = {ascl:2505.002},
    pages = {ascl:2505.002},
    archivePrefix = {ascl},
    eprint = {2505.002},
    adsurl = {https://ui.adsabs.harvard.edu/abs/2025ascl.soft05002O},
    adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}

Please also consider the citations requested for SWIFTSimIO.

Community

Code contributions are very welcome! A good place to start is the contributing guide and how to set up a development environment.

SWIFTGalaxy is licensed under GPL-3.0 and community members are expected to abide by the code of conduct.

Metadata

Release files for swiftgalaxy 3.0.2

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

Source distribution (sdist)

Source distribution for swiftgalaxy 3.0.2
File	Size	Uploaded
swiftgalaxy-3.0.2.tar.gz	2.0 MB	Jun 5, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for swiftgalaxy 3.0.2
File	Interpreter	ABI	Platform	Reset
swiftgalaxy-3.0.2-py3-none-any.whl 83.4 kB Jun 5, 2026	Python 3	none	any	Details

Total release size: 2.1 MB

Release files / swiftgalaxy-3.0.2.tar.gz

Download URL	swiftgalaxy-3.0.2.tar.gz
Size	2.0 MB
Tags	Source
SHA-256 checksum How to use checksums	`9f45914b41b6a1b08d10036f703365356a5c3d458b86fa506d6e7928e372acba`
BLAKE2b-256 checksum How to use checksums	`e80db117ceac1c2bca7860ca9201a1aacd60f55c148aa20aea7a7aa1bcf3d37f`
Upload date	Jun 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

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/swiftgalaxy
Publishing commit: github.com/SWIFTSIM/swiftgalaxy/tree/6395000737769ae54bf5d3166bca681d54df56e1

Workflow

Publishing configuration: github.com/SWIFTSIM/swiftgalaxy/blob/6395000737769ae54bf5d3166bca681d54df56e1/.github/workflows/python-publish.yml
Publishing logs: github.com/SWIFTSIM/swiftgalaxy/actions/runs/27007199237/attempts/1

Artifact

Subject: swiftgalaxy-3.0.2.tar.gz
SHA-256 checksum: 9f45914b41b6a1b08d10036f703365356a5c3d458b86fa506d6e7928e372acba Verifying attestations

Release files / swiftgalaxy-3.0.2-py3-none-any.whl

Download URL	swiftgalaxy-3.0.2-py3-none-any.whl
Size	83.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`57e8ab4fac45112fec7f26810ef3f56158881fe70ad0e26a8abc73d003356ef4`
BLAKE2b-256 checksum How to use checksums	`9457853536c80aa439aeb7e444e36f40ddb69a2771995eb316d0f4d18a372825`
Upload date	Jun 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/SWIFTSIM/swiftgalaxy
Publishing commit: github.com/SWIFTSIM/swiftgalaxy/tree/6395000737769ae54bf5d3166bca681d54df56e1

Workflow

Publishing configuration: github.com/SWIFTSIM/swiftgalaxy/blob/6395000737769ae54bf5d3166bca681d54df56e1/.github/workflows/python-publish.yml
Publishing logs: github.com/SWIFTSIM/swiftgalaxy/actions/runs/27007199237/attempts/1

Artifact

Subject: swiftgalaxy-3.0.2-py3-none-any.whl
SHA-256 checksum: 57e8ab4fac45112fec7f26810ef3f56158881fe70ad0e26a8abc73d003356ef4 Verifying attestations