astromartini 2.1.18

Synthetic datacube creation from simulations.

Overview

MARTINI is a modular package for the creation of synthetic resolved HI line observations (data cubes) of smoothed-particle hydrodynamics simulations of galaxies. The various aspects of the mock-observing process are divided logically into sub-modules handling the data cube, source, beam, noise, spectral model and SPH kernel. MARTINI is object-oriented: each sub-module provides a class (or classes) which can be configured as desired. For most sub-modules, base classes are provided to allow for straightforward customization. Instances of each sub-module class are given as parameters to the Martini class; a mock observation is then constructed by calling a handful of functions to execute the desired steps in the mock-observing process.

Full documentation can be found on ReadTheDocs.

Citing MARTINI

If your use of MARTINI leads to a publication, please cite the JOSS paper (ADS listing) and the original paper (also on ADS). You may also cite the MARTINI 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{2024JOSS....9.6860O,
    author = {{Oman}, Kyle A.},
    title = "{MARTINI: Mock Array Radio Telescope Interferometry of the Neutral ISM}",
    journal = {The Journal of Open Source Software},
    keywords = {astronomy, simulations},
    year = 2024,
    month = jun,
    volume = {9},
    number = {98},
    eid = {6860},
    pages = {6860},
    doi = {10.21105/joss.06860},
    adsurl = {https://ui.adsabs.harvard.edu/abs/2024JOSS....9.6860O},
    adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}

@ARTICLE{
    2019MNRAS.482..821O,
    author = {{Oman}, Kyle A. and {Marasco}, Antonino and {Navarro}, Julio F. and {Frenk}, Carlos S. and {Schaye}, Joop and {Ben{\'\i}tez-Llambay}, Alejandro},
    title = "{Non-circular motions and the diversity of dwarf galaxy rotation curves}",
    journal = {\mnras},
    keywords = {ISM: kinematics and dynamics, galaxies: haloes, galaxies: structure, dark matter, Astrophysics - Astrophysics of Galaxies, Astrophysics - Cosmology and Nongalactic Astrophysics},
    year = 2019,
    month = jan,
    volume = {482},
    number = {1},
    pages = {821-847},
    doi = {10.1093/mnras/sty2687},
    archivePrefix = {arXiv},
    eprint = {1706.07478},
    primaryClass = {astro-ph.GA},
    adsurl = {https://ui.adsabs.harvard.edu/abs/2019MNRAS.482..821O},
    adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}

@MISC{
    2019ascl.soft11005O,
    author = {{Oman}, Kyle A.},
    title = "{MARTINI: Mock spatially resolved spectral line observations of simulated galaxies}",
    keywords = {Software},
    howpublished = {Astrophysics Source Code Library, record ascl:1911.005},
    year = 2019,
    month = nov,
    eid = {ascl:1911.005},
    pages = {ascl:1911.005},
    archivePrefix = {ascl},
    eprint = {1911.005},
    adsurl = {https://ui.adsabs.harvard.edu/abs/2019ascl.soft11005O},
    adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}

Work that has used MARTINI includes: Oman et al. (2019), Mancera Piña et al. (2019), Chauhan et al. (2019), Mancera Piña et al. (2020), Santos-Santos et al. (2020), Glowacki et al. (2021), Bilimogga et al. (2022), Glowacki et al. (2022), Roper et al. (2023), Oman et al. (2024), Elson (2024), Perron-Cormier et al. (2025), Lin et al. (2026), Rabyang & Elson (2026) and Dado et al. (2026). The ALMASim package (Guglielmetti et al. 2023) builds on some of MARTINI’s functionality. If your work has used MARTINI and is not listed here, please let me know (by email or github issue).

Installation Notes

MARTINI works with python3 (version 3.10 or higher).

Stable releases are available via PyPI:

python3 -m pip install astromartini

and the numbered releases (starting from 2.0.0) on github. The github main branch is actively developed: things will change, bugs will happen. Any feedback is greatly appreciated via github issues or [e-mail].

The easiest way to install MARTINI is from PyPI by doing python3 -m pip install astromartini. Output to .fits files is supported by default; if output to .hdf5 format is desired use python3 -m pip install "astromartini[hdf5_output]" instead. This will also handle the installation of the required dependencies. Other optional features require additional dependencies hosted on PyPI. In particular, EAGLE, Illustris/TNG, Simba and FIRE users who wish to use the custom source modules for those simulations in MARTINI can automatically install the optional dependencies with python3 -m pip install "astromartini[eaglesource]", python3 -m pip install "astromartini[simbasource]", python3 -m pip install "astromartini[tngsource]", or python3 -m pip install "astromartini[firesource]".

Installing from github

You can browse releases that correspond to versions on PyPI (starting from 2.0.0) and download the source code. Unpack the zip file if necessary. If you’re feeling adventurous or looking for a feature under development you can so browse branches and choose one to clone. In either case you should then be able to do python3 -m pip install "martini/[optional]", where optional should be replaced by a comma separated list of optional dependencies. If this fails check that martini/ is a path pointing to the directory containing the pyproject.toml file for MARTINI. The currently available options are:

• parallel: Support for parallelizing the slower parts of Martini calculations.

• hdf5_output: Supports output to hdf5 files via the h5py package. Since h5py is hosted on PyPI, this option may be used when installing via PyPI.

• colibresource: Dependencies for the martini.sources.ColibreSource module, which greatly simplifies reading input from Colibre snapshots. Install swiftsimio and swiftgalaxy.

• eaglesource: Dependencies for the martini.sources.EAGLESource module, which greatly simplifies reading input from EAGLE simulation snapshots. Installs my Hdecompose package, providing implementations of the Rahmati et al. (2013) method for computing netural hydrogen fractions and the Blitz & Rosolowsky (2006) method for atomic/molecular fractions. Also installs my python-only version of John Helly’s read_eagle package for quick extraction of particles in a simulation sub-volume. h5py is also required.

• firesource: Dependencies for the martini.sources.FIRESource module, which greatly simplifies reading input from FIRE simulation snapshots. Installs the gizmo-analysis, halo-analysis and utilities-awetzel packages.

• magneticumsource: Dependencies for the martini.sources.MagneticumSource module, which supports the Magneticum simulations via the g3read package.

• simbasource: Dependencies for the martini.sources.SimbaSource module, which greatly simplifies reading input from Simba snapshots. Installs h5py.

• swiftgalaxysource: Dependencies for the martini.sources.SWIFTGalaxySource module, which greatly simplifies reading input from SWIFT simulations. Installs swiftsimio and swiftgalaxy.

• tngsource: Dependencies for the martini.sources.TNGSource module, which greatly simplifies reading input from IllustrisTNG (and original Illustris) snapshots. Installs my Hdecompose package, providing implementations of the Rahmati et al. (2013) method for computing netural hydrogen fractions and the Blitz & Rosolowsky (2006) method for atomic/molecular fractions.

• all: All of the above.

• testing: Dependencies for code validation and testing (for developers).

• docs: Dependencies for building the documentation (for developers).

• dev: A full development environment with verything included in all, testing and docs (for developers).

There is also a martini.sources.SOSource module with additional dependencies, which provides unofficial support for several simulation datasets hosted on specific systems. This is intended mostly for my own use, but APOSTLE, C-EAGLE/Hydrangea and Auriga users may contact me for further information.

Getting started

See the help for martini.Martini for an example script to configure MARTINI and create a datacube. This example can be run by doing:

python -c "from martini import demo; demo()"

MARTINI has (so far) been successfully run on the output of these simulations:

• EAGLE (also APOSTLE, C-EAGLE/Hydrangea)

• IllustrisTNG (also Illustris, Auriga)

• Simba

• FIRE

• Magneticum

• MaGICC, Marvelous-Merian (and therefore in principle other N-body shop projects)

• Colibre (test runs)

I attempt to support publicly available simulations with a customized source module. If your simulation is public and not supported, please contact me. Currently custom source modules exist for:

• EAGLE (martini.sources.EAGLESource)

• IllustrisTNG (martini.sources.TNGSource; also works with Illustris)

• FIRE (martini.sources.FIRESource)

• Simba (martini.sources.SimbaSource)

• Magneticum (martini.sources.MagneticumSource)

• SWIFT (martini.sources.SWIFTGalaxySource)

• Colibre (martini.sources.ColibreSource)

Example notebooks are available for supported, publicly available simulations.