Skip to content

Commit

Permalink
DOCS: Update 'README.md' and readthedocs index page
Browse files Browse the repository at this point in the history
  • Loading branch information
@lzkelley
lzkelley committed Feb 19, 2024
1 parent 0048ed7 commit 8ab6c7f
Show file tree
Hide file tree
Showing 2 changed files with 81 additions and 47 deletions.
115 changes: 74 additions & 41 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
# holodeck

[//]: # (Badges)
[![GitHub version](https://badge.fury.io/gh/nanograv%2Fholodeck.svg)](https://badge.fury.io/gh/nanograv%2Fholodeck)
[![build](https://github.com/nanograv/holodeck/actions/workflows/unit-tests-ci.yaml/badge.svg)](https://github.com/nanograv/holodeck/actions/workflows/unit-tests-ci.yaml)
[![codecov](https://codecov.io/gh/nanograv/holodeck/branch/main/graph/badge.svg?token=K63WQH3ED9)](https://codecov.io/gh/nanograv/holodeck)
[![Documentation Status](https://readthedocs.org/projects/holodeck-gw/badge/?version=main)](https://readthedocs.org/projects/holodeck-gw/)
Expand All @@ -10,81 +9,115 @@

<img src="docs/media/holodeck_logo.png" width="260" alt="holodeck logo">

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.
This package provides a comprehensive framework for MBH binary population synthesis. The framework includes modules to perform population synthesis using a variety of methodologies from semi-analytic models, to cosmological hydrodynamic simulations, and even observationally-derived galaxy merger catalogs.

## Installation
## Getting Started

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`.
(1) Read the [getting started guide](https://holodeck-gw.readthedocs.io/en/main/getting_started/index.html).
(2) Install `holodeck` following the [Installation](#installation) instructions below.
(3) Explore the [package demonstration notebooks](https://github.com/nanograv/holodeck/tree/main/notebooks).

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`
## Installation

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.
The `holodeck` framework is currently under substantial, active development. Stable versions are now available with `pip install holodeck-gw` (see [holodeck on pypi](https://pypi.org/project/holodeck-gw)). However, recent versions and many development tools will not generally be available with ``pip`` or ``conda`` install.

### MPI
`holodeck` requires ``python >= 3.9`` (with support for: ``3.9, 3.10, 3.11``). The recommended installation is:

For some scripts (particularly for generating libraries), an MPI implementation is required (e.g. `openmpi`), along with the [`mpi4py` package](https://github.com/mpi4py/mpi4py). 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.
(0) OPTIONAL & recommended: create and activate a new **anaconda** environment to isolate your build:

To see if you have `mpi4py` installed, run `python -c 'import mpi4py; print(mpi4py.__version__)'` from a terminal.
```bash
conda create --name holo311 python=3.11; conda activate holo311
```

#### macos
Note that you will need to activate this environment every time you want to use holodeck. If you're not familiar with **anaconda**, take a look at their official [Getting started guide](https://conda.io/projects/conda/en/latest/user-guide/getting-started.html#managing-python). To use your anaconda environment with jupyter notebooks, make sure to add this environment to your ipython kernels:

If you are using homebrew on macos, you should be able to simply run: `brew install mpi4py` which will [include the required openmpi implementation](https://mpi4py.readthedocs.io/en/latest/install.html#macos). 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`.
```bash
conda install -c conda-forge ipykernel
python -m ipykernel install --user --name=holo311
```

(1) Clone the `holodeck` repository, and move into the repo directory:

## Quickstart
```bash
git clone https://github.com/nanograv/holodeck.git; cd holodeck
```

The best way to get started is using the demonstration/testing notebooks included in the `notebooks/` directory.
(2) Install the required external packages specified in the requirements file:

## Documentation
```bash
pip install -r requirements.txt
```

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](https://readthedocs.org/projects/holodeck-gw) are being written and improved, and a methods paper is in preparation.
OPTIONAL: install development requirements::

## Contributing
```bash
pip install -r requirements-dev.txt
```

This project is being led by the [NANOGrav](http://nanograv.org/) Astrophysics Working Group.
(3) Build the required c libraries from `holodeck` `cython` code:

Details on contributions and the mandatory code of conduct can be found in the [CONTRIBUTING.md](./CONTRIBUTING.md) file.
```bash
python setup.py build_ext -i
```

To-do items and changes to the API should be included in the [CHANGELOG.md](./CHANGELOG.md) file.
(4) Perform a development/editable local installation:

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).
```bash
python setup.py develop
```

### Testing
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. Note that any changes to the `cython` library files do still require a rebuild by running steps (3) and (4) above.

(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`.
### MPI

For some scripts (particularly for generating libraries), an MPI implementation is required (e.g. `openmpi`), along with the [mpi4py package](https://github.com/mpi4py/mpi4py). 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 already have an MPI implementation installed on your system, you should be able to install `mpi4py` with anaconda: `conda install mpi4py`. To see if you have `mpi4py` installed, run `python -c 'import mpi4py; print(mpi4py.__version__)'` from a terminal.

### Formatting
**macos users**: if you are using homebrew on macos, you should be able to simply run: `brew install mpi4py` which will [include the required openmpi implementation](https://mpi4py.readthedocs.io/en/latest/install.html#macos).

New code should generally abide by PEP8 formatting, with [`numpy` style docstrings](https://numpydoc.readthedocs.io/en/latest/format.html). Exceptions are:

* lines may be broken at either 100 or 120 columns
## Quickstart

### Notebooks
(1) Read the [Getting Started Guide](https://holodeck-gw.readthedocs.io/en/main/getting_started/index.html).
(2) Explore the [package demonstration notebooks in `holodeck/notebooks`](https://github.com/nanograv/holodeck/tree/main/notebooks).

Please strip all notebook outputs before commiting notebook changes. The [`nbstripout`](https://github.com/kynan/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:
## Documentation

* (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)
Full package documentation for `holodeck` is available on [readthedocs](https://holodeck-gw.readthedocs.io/en/main/).

## Copyright

Copyright (c) 2023, NANOGrav
## Contributing & Development

The `holodeck` package uses an [MIT license](./LICENSE).
Contributions are not only welcome but encouraged, anywhere from new modules/customizations to bug-fixes to improved documentation and usage examples. Please see [Development & Contributions](https://holodeck-gw.readthedocs.io/en/main/development.html).

## Copyright

## Attribution
Copyright (c) 2024, NANOGrav

A NANOGrav paper on `holodeck` is currently in preparation.
The `holodeck` package uses an [MIT license](./LICENSE).


## Acknowledgements
## Attribution & Referencing

A dedicated paper on ``holodeck`` is currently in preparation, but the package is also described in the recent [astrophysics analysis from the NANOGrav 15yr dataset](https://ui.adsabs.harvard.edu/abs/2023ApJ...952L..37A/abstract).


```tex
@ARTICLE{2023ApJ...952L..37A,
author = {{Agazie}, Gabriella and {et al} and {Nanograv Collaboration}},
title = "{The NANOGrav 15 yr Data Set: Constraints on Supermassive Black Hole Binaries from the Gravitational-wave Background}",
journal = {\apjl},
year = 2023,
month = aug,
volume = {952},
number = {2},
eid = {L37},
pages = {L37},
doi = {10.3847/2041-8213/ace18b},
archivePrefix = {arXiv},
eprint = {2306.16220},
primaryClass = {astro-ph.HE},
adsurl = {https://ui.adsabs.harvard.edu/abs/2023ApJ...952L..37A},
}
```
13 changes: 7 additions & 6 deletions docs/source/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ holodeck

`holodeck on github <https://github.com/nanograv/holodeck>`_

This package is aimed at providing a comprehensive framework for MBH binary population synthesis. The framework includes modules to perform population synthesis using a variety of methodologies from semi-analytic models, to cosmological hydrodynamic simulations, and even observationally-derived galaxy merger catalogs.
This package provides a comprehensive framework for MBH binary population synthesis. The framework includes modules to perform population synthesis using a variety of methodologies from semi-analytic models, to cosmological hydrodynamic simulations, and even observationally-derived galaxy merger catalogs.

**This File:**

Expand Down Expand Up @@ -63,16 +63,17 @@ This package is aimed at providing a comprehensive framework for MBH binary popu
Getting Started
===============

| (1) Read the ``holodeck`` :doc:`getting started <getting_started/index>` guide.
| (2) Install ``holodeck`` following the `installation`_ instructions below.
| (1) Read the :doc:`getting started <getting_started/index>` guide.
| (2) Install |holodeck| following the `installation`_ instructions below.
| (3) Explore the `package demonstration notebooks <https://github.com/nanograv/holodeck/tree/main/notebooks>`_.
| (4) Read the `Development & Contributions <development>`_ guide.

Installation
============

The ``holodeck`` framework is currently under substantial, active development. Recent versions will not generally be available with ``pip`` or ``conda`` install. Currently ``holodeck`` requires ``python >= 3.9`` (tests are run on versions ``3.9``, ``3.10``, ``3.11``). The recommended installation is:
The |holodeck| framework is currently under substantial, active development. Stable versions are now available with ``pip install holodeck-gw`` (see `holodeck on pypi <https://pypi.org/project/holodeck-gw>`_). However, recent versions and many development tools will not generally be available with ``pip`` or ``conda`` install.

|holodeck| requires ``python >= 3.9`` (with support for: ``3.9, 3.10, 3.11``). The recommended installation is:

0) OPTIONAL & recommended: create and activate a new **anaconda** environment to isolate your build::

Expand Down Expand Up @@ -103,7 +104,7 @@ The ``holodeck`` framework is currently under substantial, active development.

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. Note that any changes to the cython library files do still require a rebuild by running steps (3) and (4) above.
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. Note that any changes to the ``cython`` library files do still require a rebuild by running steps (3) and (4) above.

MPI
---
Expand Down

0 comments on commit 8ab6c7f

Please sign in to comment.