holodeck-gw 1.3

holodeck: Massive black hole (MBH) binary simulator for pulsar timing array signals.

holodeck

Massive Black-Hole Binary Population Synthesis for Gravitational Wave Calculations ≋●≋●≋

This package is aimed at providing a comprehensive framework for MBH binary population synthesis. The framework includes modules to perform pop synth using a variety of methodologies to get a handle on both statistical and systematic uncertainties. Currently, binary populations can be synthesis based on: cosmological hydrodynamic simulations (Illustris), semi-analytic/semi-empirical models (SAMs), and observational catalogs of local galaxies and/or quasars.

Installation

The holodeck framework is currently under substantial, active development. It will not be available on pypi (pip) or via conda install until it has stabilized. Currently holodeck requires python >= 3.9, and tests are run on versions 3.9, 3.10, 3.11.

The recommended installation for active development is to:

0. OPTIONAL: create and activate a new anaconda environment to isolate your build: conda create --name holo310 python=3.10; conda activate holo310
1. Clone the holodeck repository: git clone https://github.com/nanograv/holodeck.git
2. Install the required external packages specified in the requirements file: pip install -r requirements.txt. OPTIONAL: install development requirements: pip install -r requirements-dev.txt
3. Build the required c libraries from holodeck cython code: cd holodeck; python setup.py build_ext -i
4. Perform an development/editable local installation: python setup.py develop

The 'editable' installation allows the code base to be modified, and have those changes take effect when using the holodeck module without having to rebuild/reinstall it.

MPI

For some scripts (particularly for generating libraries), an MPI implementation is required (e.g. openmpi), along with the mpi4py package. This is not included as a requirement in the requirements.txt file as it significantly increases the installation complexity, and is not needed for many holodeck use cases. If you need the additional functionality, try installing mpi4py and if needed an MPI implementation.

To see if you have mpi4py installed, run python -c 'import mpi4py; print(mpi4py.__version__)' from a terminal.

macos

If you are using homebrew on macos, you should be able to simply run: brew install mpi4py which will include the required openmpi implementation. If you already have an MPI implementation installed, and you are using anaconda, you should be able to install the mpy4py python package with: conda install mpi4py.

Quickstart

The best way to get started is using the demonstration/testing notebooks included in the notebooks/ directory.

Documentation

The primary sources of documentation for holodeck are this README.md file, the notebooks included in the notebooks/ directory, and docstrings included in the source code directly. readthedocs documentation are being written and improved, and a methods paper is in preparation.

Contributing

This project is being led by the NANOGrav Astrophysics Working Group.

Details on contributions and the mandatory code of conduct can be found in the CONTRIBUTING.md file.

To-do items and changes to the API should be included in the CHANGELOG.md file.

Contributions are not only welcome but encouraged, anywhere from new modules/customizations to bug-fixes to improved documentation and usage examples. The git workflow is based around a main branch which is intended to be (relatively) stable and operational, and an actively developed dev branch. New development should be performed in "feature" branches (made off of the dev branch), and then incorporated via pull-request (back into the dev branch).

Testing

(Unit)tests should be developed in two ways: for basic functions/behaviors, standard unit-tests can be placed in the holodeck/tests/ directory. More complex functionality should be tested in notebooks (in notebooks/) where they can also be used as demonstrations/tutorials for that behavior. The python script scripts/convert_notebook_tests.py converts target notebooks into python scripts in the holodeck/tests/ directory, which can then be run by pytest. The script scripts/holotest.sh will run the conversion script and then run pytest.

Formatting

New code should generally abide by PEP8 formatting, with numpy style docstrings. Exceptions are:

• lines may be broken at either 100 or 120 columns

Notebooks

Please strip all notebook outputs before commiting notebook changes. The nbstripout package is an excellent option to automatically strip all notebook output only in git commits (i.e. it doesn't change your notebooks in-place). You can also use nbconvert to strip output in place: jupyter nbconvert --clear-output --inplace <NOTEBOOK-NAME>.ipynb.

To install this package for just this repository:

• (1) install: pip install --upgrade nbstripout or conda install -c conda-forge nbstripout
• (2) enable: nbstripout --install --attributes .gitattributes (run this in the top-level holodeck/ directory)

Copyright

Copyright (c) 2023, NANOGrav

The holodeck package uses an MIT license.

Attribution

A NANOGrav paper on holodeck is currently in preparation.

Acknowledgements