████████████████████████████████████
▄                                  ▄
▄ ░█▀█░█▀▀░▀█▀░█▀█░█░█░▀█▀░█░█░█▀▀ ▄
▄ ░█░█░█░░░░█░░█▀█░▀▄▀░░█░░█░█░▀▀█ ▄
▄ ░▀▀▀░▀▀▀░░▀░░▀░▀░░▀░░▀▀▀░▀▀▀░▀▀▀ ▄
▄                                  ▄
████████████████████████████████████

Octavius: The Next-Generation Simulation Analysis Toolkit

Octavius is a high-performance, fully-parallelised code designed to produce analysis catalogues of SPH simulation snapshots. Written entirely in Python with minimal dependencies and all features ready out-of-the-box, it slots cleanly into analysis workflows.

Catalogues are stored as HDF5 files containing physical properties and membership mapping for both haloes and galaxies, along with cosmological information from the snapshot.

Please refer to the documentation for more information.

Install

Octavius is packaged on pip, with a planned conda-forge deployment in the near-future. It can be quickly installed from the terminal by running:

    pip install octavius

The package is (currently) pinned to relatively recent dependencies and it is therefore recommended to use a tool like uv for version resolution.

Features

• Supports SWIFT and GIZMO snapshots
• Supports AHF halo catalogues (coming soon: HBT HERONS)
• Produces snapshot-agnostic catalogues
• Built-in galaxy finding with a 6D friends-of-friends algorithm
• Computes over fifty properties for haloes and galaxies (including subhaloes)
• Photometry in all FSPS-compatible bands with dust attenuation (no radiative transfer)
• User-friendly catalogues contain membership mapping
• Unit-tested analysis pipeline

Quickstart Guide

To analyse a snapshot, you must specify parameters with a configuration file. Once installed, a config YAML file for you to fill in can be generated in your current directory by running:

    octavius init

The analysis can then be called either from the command line, or a Python script.

    mpiexec -n 2 octavius analyse -c /path/to/config.yaml

    from pathlib import Path
    from octavius import analyse_snapshot, OctaviusConfig

    config_filepath = Path("/path/to/config.yaml")
    config = OctaviusConfig.from_yaml(config_filepath)
    catalogue_path = analyse_snapshot(config)  # analyse_snapshot() is natively MPI-aware and can be run in serial too

It is recommended to use the command-line method for larger snapshots and more complex workflows, as it is more flexible. For more information, please run:

    octavius analyse --help

An object-oriented API is provided for loading and conveniently interfacing with catalogues. This includes methods of mapping the galaxies and haloes in the catalogue to their constituent particles in the raw snapshot as well as group hierarchies (including subhaloes).

    from pathlib import Path
    from octavius import load_catalogue

    catalogue_filepath = Path("/path/to/catalogue.hdf5")

    cat = load_catalogue(catalogue_filepath)

    star_mass_grams = cat.galaxies.get_dataset("mass_star", to_units="g")  # array of galaxy stellar masses in grams

Photometry requires a bespoke data file which requires FSPS to generate. The table can take a while to generate, and stores all necessary data for photometry; there is no runtime dependency on FSPS.

    from pathlib import Path
    from octavius import generate_photometry_table, generate_photometry_table_from_sp

    photometry_table_filepath = Path("/path/to/table.hdf5")

    generate_photometry_table(photometry_table_filepath)  # default method with basic options 

    import fsps
    sp = fsps.StellarPopulation(...)  # full control over FSPS options
    generate_photometry_table_from_sp(photometry_table_filepath, sp)

Octavius is written mostly in numba, which relies on JIT compilation; this can add a minute or two of overhead when first run, but thereafter, the compiled functions are cached.

Dependencies

• numba
• numpy
• astropy
• h5py
• mpi4py

Optional:

• fsps (for photometry data tables)

Citing

Octavius can be cited with Zenodo doi: 10.5281/zenodo.22166634.

Beta

The package is currently in beta pre-release; please keep this in mind if using it for analysis. You are encouraged to please play around with the code and report any bugs or inaccuracies which may arise.

Caesar

Octavius is the spiritual successor to Caesar (source code). There is a short guide for caesar users in the documentation.

Licence

Octavius is licenced under the BSD 3-Clause licence.

Contributing

Contributions and bug reports are warmly encouraged. The package is currently pinned to relatively recent versions of its dependencies, and any investigation as to whether these can be relaxed would be most welcome; otherwise, please refer to CONTRIBUTING.md for more detailed information.

Contributors

• JP Duminy, University of Edinburgh
• Jakub Szpila, Nicolaus Copernicus Astronomical Center

Last updated by JP Duminy, 29/08/2026.