Getting Started

swiftgalaxy facilitates analyses of individual galaxies from cosmological hydrodynamical simulations executed with the SWIFT code. The core SWIFTGalaxy class makes selecting particles belonging to a galaxy, transforming their coordinates, masking its particle arrays, working with spherical or cylindrical coordinates, accessing its integrated properties computed by a halo finder, and more, easy. It is built upon the SWIFTDataset from swiftsimio and takes advantage of that module’s lazy-loading and unit-awareness features. Users already familiar with usage of swiftsimio will find that any syntax to interact with a SWIFTDataset also works with a SWIFTGalaxy.

Requirements

python3.10 or higher is required.

Python packages

Required:

  • swiftsimio (v10 or higher), required to provide the SWIFTDataset class and related functionality (note that swiftsimio has additional required dependencies).

  • numpy, required to support various array operations.

  • unyt, required for unit calculations.

  • scipy, required to specify rotations via the Rotation class.

Optional:

  • velociraptor, required to enable support for Velociraptor halo finder outputs.

  • soap (soap on github not the soap from PyPI!), for generating example SOAP data sets.

  • caesar (caesar on github not the caesar from PyPI!), required to enable support for Caesar catalogues.

  • astropy, used in generating example data sets.

  • h5py, used to generate example data sets.

Additional optional packages for developers:

  • ruff for code formatting and style checks.

  • mypy for type checking (run mypy --install-types --non-interactive after installation).

  • pytest to run the test suite.

  • numpydoc to check for issues in docstrings.

  • flake8 to check for code style issues.

  • pytest-cov to generate test coverage reports.

  • sphinx-lint to check for style issues in narrative documentation files.

And for building the docs:

  • sphinx

  • sphinx-rtd-theme

  • sphinx-design

  • recommonmark

Installing

swiftgalaxy can be installed using the python packaging manager, pip, or any other packaging manager that you wish to use:

pip install swiftgalaxy

Note that this will also install required dependencies. 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

Installation for development

To set up the code for development, first clone the latest main branch from github: git clone https://github.com/SWIFTSIM/swiftgalaxy.git and install with pip using the -e (editable) flag, and specify development dependencies with [dev]: pip install -e swiftgalaxy/[dev].

You should also install the dependencies for SOAP and Caesar (cannot be declared as dependencies in a PyPI-distributed package because they are hosted on github, so omitted from the pyproject.toml file for simplicity):

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

Finally, you should install type definitions for mypy: mypy --install-types --non-interactive.

You can check that the installation and your environment is ready for development work by moving to the code root directory (cd swiftgalaxy) and running the following checks:

flake8
ruff format --check
ruff check
mypy
python -m numpydoc lint swiftgalaxy/*.py
sphinx-lint --max-line-length 90 -e all docs/source/
pytest --cov --cov-branch

You may wish to set up the following pre-commit hook:

#!/bin/sh

flake8 || exit 1
ruff format --check || exit 1
ruff check || exit 1
mypy || exit 1
python -m numpydoc lint swiftgalaxy**/*.py || exit 1
sphinx-lint --max-line-length 90 -e all docs/source/ || exit 1

exit 0

and pre-push hook:

#!/bin/sh

remote="$1"
url="$2"

flake8 || exit 1
ruff format --check || exit 1
ruff check || exit 1
mypy || exit 1
python -m numpydoc lint swiftgalaxy**/*.py || exit 1
sphinx-lint --max-line-length 90 -e all docs/source/ || exit 1
pytest || exit 1

exit 0

Quick start

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

Like a SWIFTDataset, all data are loaded ‘lazily’ on demand.

However, information from the halo catalogue 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 catalogue. 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 information are available:

sg.units
sg.metadata

swiftgalaxy supports Python’s tab completion features. This means that you can browse the available attributes of objects in an interactive interpreter by starting to type an attribute (or just a trailing dot) and pressing tab twice. A few examples to help start exploring:

  • sg.<tab><tab>

  • sg.gas.<tab><tab>

  • sg.halo_catalogue.<tab><tab>

The further features of a SWIFTGalaxy are detailed in the next sections.