halocat

halocat provides a compact Python interface for halo-catalogue analysis in cosmological N-body simulations. The core object is halocat.HaloCat, which stores aligned halo fields, tracks basic metadata, and exposes common measurements through a single API.

The package also includes project-specific helpers for the DEGRACE-pilot data products:

• reformatting raw BDM CatshortV halo catalogues into HDF5
• copying matter power-spectrum files into a standard output tree
• measuring and saving halo mass functions for reformatted catalogues
• loading and plotting the resulting pk_mm.dat and hmf.hdf5 products

Features

• validated halo field container with consistent array-length checks
• support for arbitrary one-dimensional halo properties alongside standard position, velocity, and mass fields
• metadata handling for boxsize, redshift, periodic, cosmology, and per-field units
• catalogue loading from BDM text files, HDF5, NPZ, NPY structured arrays, and delimited text tables
• selection helpers for mass ranges, field predicates, explicit masks, and axis-aligned regions
• measurement helpers for halo mass functions, 2PCF, pairwise velocity moments, bias, and generic binned statistics
• structured dataclass results instead of position-dependent tuples

Unit conventions

• Positions: x, y, z in Mpc/h
• Velocities: vx, vy, vz in km/s
• Halo mass: mass in Msun/h

Quick example

import numpy as np

from halocat import HaloCat

cat = HaloCat(
    x=np.array([0.0, 10.0, 20.0]),
    y=np.array([0.0, 0.0, 0.0]),
    z=np.array([0.0, 0.0, 0.0]),
    vx=np.array([100.0, 120.0, 140.0]),
    vy=np.zeros(3),
    vz=np.zeros(3),
    mass=np.array([1.0e12, 2.5e12, 6.0e12]),
    boxsize=1000.0,
    redshift=0.25,
)

cat = cat.select_by_mass(1.0e12, 1.0e14)
hmf = cat.measure_dndlog10M(log10mass_edges=np.arange(12.0, 13.1, 0.25))
xi = cat.measure_2PCF(np.array([0.0, 5.0, 15.0, 30.0]))

print(cat.summary())
print(hmf.number_density[:3])
print(xi.xi[:3])

Installation

For a basic editable install:

pip install -e .

Useful optional dependency groups:

• .[io] for HDF5 and pandas-backed helpers
• .[plot] for matplotlib plotting helpers
• .[docs] for MkDocs
• .[test] for pytest
• .[dev] for the combined local development stack

Building the docs

Install the documentation dependency set and run MkDocs from the repository root:

pip install -e ".[docs]"
mkdocs build
mkdocs serve