Merge branch 'dev' into docs

* dev: (416 commits)
  Work on docstrings in `holodeck.gravwaves` and `holodeck.simple_sam`
  Add some docstrings to `sam_for_params` in Hard04 and Eccen01 classes
  DOCS: Tweak
  BUG: fix broken github actions, cannot use absolute paths in setup.py
  BUG: readthedocs build error, 4
  BUG: readthedocs build error, 3
  BUG: readthedocs build error, 2
  BUG: readthedocs build error
  Update 'docs/conf.py' so that 'make html' does everything needed, and so that readthedocs will follow suit
  Try to get readthedocs build to work
  DOCS: try to fix minor docstring/sphinx issues
  Add back in doc-files, seems to be generally building okay with sphinx
  Fresh start on documentation
  Remove deprecated version of holodeck paper (see dedicated repo)
  Notebook cleanup
  Update host-relations.ipynb
  Update relations.py
  Update population.py
  Update relations.py
  Update sam.py
  ...

.github/workflows/unit-tests-ci.yaml

@@ -12,20 +12,31 @@ on:
 
 jobs:
   test:
-    name: Test Python ${{ matrix.python-version }}, ${{ matrix.os }}
+    name: Test Python ${{ matrix.python-version }}, ${{ matrix.os }}, ${{ matrix.mpi }}
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ubuntu-latest] #[macOS-latest, windows-latest]
-        # python-version: ['3.8', '3.9', '3.10']
-        python-version: ['3.10']
+        # os: [ubuntu-latest, macOS-latest, windows-latest]
+        os: [ubuntu-latest, macOS-latest]
+        # os: [ubuntu-latest]
+        python-version: ['3.9', '3.10', '3.11']
+        # python-version: ['3.10']
+        # mpi: [ 'mpich', 'openmpi', 'intelmpi']
+        # mpi: ['openmpi']
 
     steps:
     - name: Check out repository
       uses: actions/checkout@v2
       with:
         fetch-depth: 2
 
+    # Install MPI (required to build mpi4py)
+    # see: https://github.com/mpi4py/setup-mpi
+    # - name: Setup MPI
+    #     uses: mpi4py/setup-mpi@v1
+    #     with:
+    #       mpi: ${{ matrix.mpi }}
+
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v2
       with:

.gitignore

@@ -134,3 +134,7 @@ run_gen_lib_sams__*
 *.html
 .gitattributes
 *.slurm
+
+# Mac Desktop Services
+.DS_Store
+.history

.readthedocs.yml

@@ -7,13 +7,13 @@ version: 2
 
 # Set the version of Python and other tools you might need
 build:
-  os: ubuntu-20.04
+  os: ubuntu-22.04
   tools:
     python: "3.9"
-    # You can also specify other tool versions:
-    # nodejs: "16"
-    # rust: "1.55"
-    # golang: "1.17"
+  jobs:
+    post_install:
+      - python setup.py build_ext -i
+      - python setup.py develop
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

LICENSE

@@ -1,7 +1,7 @@
 
 MIT License
 
-Copyright (c) 2022 NANOGrav
+Copyright (c) 2023 NANOGrav
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -4,15 +4,15 @@
 [![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://holodeck-gw.readthedocs.io/en/main/?badge=main)
+[![Documentation Status](https://readthedocs.org/projects/holodeck-gw/badge/?version=main)](https://readthedocs.org/projects/holodeck-gw/)
 
 *Massive Black-Hole Binary Population Synthesis for Gravitational Wave Calculations ≋●≋●≋*
 
 This package, which is actively under development, 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.8`, and tests are run on versions `3.8`, `3.9`, `3.10`.
+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:
 
@@ -24,6 +24,16 @@ The recommended installation for active development is to:
 
 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](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.
+
+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](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`.
+
 
 ## Quickstart
 
@@ -65,7 +75,7 @@ To install this package for just this repository:
 
 ## Copyright
 
-Copyright (c) 2022, NANOGrav
+Copyright (c) 2023, NANOGrav
 
 The `holodeck` package uses an [MIT license](./LICENSE).