Merge branch 'dev'

* dev: (48 commits)
  Bump to v1.6
  BUG: fix issue with how 'param_samples' was being compared to None.
  BUG: use codecov token stored to github repository secrets
  BUG: temporarily remove some rarely-used packages from the global requirements file, as they are causing problems
  DOCS: update CHANGELOG and librarian version
  BUG: minor bug fixes
  Deprecate 'holodeck.librarian.libraries' ==> 'holodeck.librarian.lib_tools'
  Store parameters in each simulation file.  Load param-samples when combining 'domain' runs, and save to combined domain file.
  Add separate names for combined simulation 'library' and 'domain'
  Full (trial) implementation of domain construction with 'combine' working.
  Pass existing 'log' to sam instances.  Fix issue with bf_frac_lo extending to 0.0 (cant)
  In 'normalized_params', use 'None' values to produce default values.  Added tests also.
  BUG: issue with loading saves
  In 'fit_spectra' only require match to library file name ending, not whole name
  In gen_lib, add in 'verbose' CL argument; work on setting up 'domain' exploration runs
  When loading saved parameter-spaces, access class-name from save file
  BUG: Try to fix issue with loggers not setting correct level when using both stream and file IO
  Cleanup; move code to setup pspace to separate function
  Add script for copying sets of libraries into a single output folder for transfer
  Move constants to root of librarian module
  ...

.github/workflows/coverage.yaml

@@ -64,9 +64,10 @@ jobs:
         pytest -v --cov=./ --cov-report term --cov-report=xml --color=yes
 
     - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v3
+      uses: codecov/codecov-action@v4
       with:
         name: codecov-${{ matrix.os }}-py${{ matrix.python-version }}
+        token: ${{ secrets.CODECOV_TOKEN }} # required
         env_vars: OS,PYTHON
         fail_ci_if_error: true
         verbose: true

CHANGELOG.md

@@ -19,6 +19,35 @@
 
 ## Current
 
+## v1.6 - 2024/05/01
+
+* DEPRECATIONS:
+    * `holodeck.librarian.py` ==> `holodeck.librarian.lib_tools`
+        * Rename submodule.  All components remain the same.  All `lib_tools` elements are now also imported into the `librarian` namespace.  i.e. elements like `holodeck.librarian.lib_tools._Param_Space` will now be accessible via `holodeck.librarian._Param_Space`.
+    * Library filenames:
+        * Standard library simulation files will now be saved to the 'library_sims' subdirectory, and filenames 'library__p######.npz'.  Combined library files will now be 'sam-library.hdf5'.
+        * 'Domain' simulation files will be saved to the 'domain_sims' subdirectory, and filenames 'domain__p######.npz'.  Combined domain files will now be 'sam-domain.hdf5'.
+
+* BUGS:
+    * Semi-Analytic Models
+        * `Semi_Analytic_Model._dynamic_binary_number_at_fobs_inconsistent` was not checking for systems that had already coalesced.  Only effected GW-only evolution using the python version of the calculation.
+
+* DEFAULTS:
+    * Semi-Analytic Models
+        * `Semi_Analytic_Models` instances now use galaxy merger-rates (instead of galaxy pair-fractions and merger-times) by default.  To use GPF+GMT SAMs, the user must pass in at least a GPF instance manually.
+
+* General Changes
+
+    * Semi-Analytic Models (`holodeck.sams`)
+        * Improve accuracy of dynamic binary number calculation for consistent evolution models.
+
+    * `holodeck.librarian`
+        * Added functionality to construct 'domain' sets of simulations, to explore each parameter in a parameter-space one at a time.
+        * NOTE: Standard library files will now be called "sam-library.hdf5" instead of "sam_lib.hdf5"
+
+
+## v1.5.2 - 2024/04/12
+
 * DEPRECATIONS
     * `host_relations.py`: remove the `mamp` parameter and `MASS_AMP` attributes in the MMBulge relationships, and use `mamp_log10` and `MASS_AMP_LOG10` exclusively.
 

docs/source/api_ref/holodeck.librarian.libraries.rst → docs/source/api_ref/holodeck.librarian.lib_tools.rst

@@ -1,8 +1,8 @@
 ============================
-holodeck.librarian.libraries
+holodeck.librarian.lib_tools
 ============================
 
-.. automodule:: holodeck.librarian.libraries
+.. automodule:: holodeck.librarian.lib_tools
     :members:
     :private-members:
     :undoc-members:

docs/source/api_ref/holodeck.librarian.rst

@@ -15,7 +15,7 @@ holodeck.librarian module
     holodeck.librarian.combine
     holodeck.librarian.fit_spectra
     holodeck.librarian.gen_lib
-    holodeck.librarian.libraries
+    holodeck.librarian.lib_tools
     holodeck.librarian.param_spaces
     holodeck.librarian.param_spaces_classic
     holodeck.librarian.posterior_populations

docs/source/getting_started/libraries.rst

@@ -12,7 +12,7 @@ Generating and Using Holodeck Libraries
 Libraries Overview
 ==================
 
-|holodeck| 'libraries' are collections of simulations in which a certain set of parameters are varied, producing different populations and/or GW signatures at each sampled parameter value.  Libraries are run from the same parameter-space and using the same hyper parameters (for example, the functional form that is assumed for the galaxy stellar-mass function).  Libraries are constructed using the :py:mod:`~holodeck.librarian` module, with a 'parameter space' class that organizes the different simulations.  The base-class is called :py:class:`~holodeck.librarian.libraries._Param_Space` (defined in the :py:mod:`holodeck.librarian.libraries` file), and all parameter space classes inherit from this, and should typically be prefixed by ``PS_`` to denote that they are parameter spaces.  The parameter-space subclasses implement a number of parameters that are varied.  Each parameter is implemented as a subclass of :py:class:`~holodeck.librarian.libraries._Param_Dist`, for example the :py:class:`~holodeck.librarian.libraries.PD_Uniform` class that implements a uniform distribution.
+|holodeck| 'libraries' are collections of simulations in which a certain set of parameters are varied, producing different populations and/or GW signatures at each sampled parameter value.  Libraries are run from the same parameter-space and using the same hyper parameters (for example, the functional form that is assumed for the galaxy stellar-mass function).  Libraries are constructed using the :py:mod:`~holodeck.librarian` module, with a 'parameter space' class that organizes the different simulations.  The base-class is called :py:class:`~holodeck.librarian.lib_tools._Param_Space` (defined in the :py:mod:`holodeck.librarian.lib_tools` file), and all parameter space classes inherit from this, and should typically be prefixed by ``PS_`` to denote that they are parameter spaces.  The parameter-space subclasses implement a number of parameters that are varied.  Each parameter is implemented as a subclass of :py:class:`~holodeck.librarian.lib_tools._Param_Dist`, for example the :py:class:`~holodeck.librarian.lib_tools.PD_Uniform` class that implements a uniform distribution.
 
 As an example, the fiducial library and parameter space for :doc:`the 15yr astrophysics analysis <nanograv_15yr>` was the 'phenomenological uniform' library, implemented as :py:class:`~holodeck.librarian.param_spaces_classic.PS_Classic_Phenom_Uniform` (at the time, it was internally called ``PS_Uniform_09B``).  This library spanned a 6D parameter space using a 'phenomenological' binary evolution model, and assuming a uniform distribution in sampling from the parameter priors.  Two parameters from the galaxy stellar-mass function were varied, along with two parameters from the M-MBulge relationship, and two parameters from the hardening model.
 
@@ -21,14 +21,14 @@ Parameter Spaces and Distributions
 ==================================
 **NOTE: currently parameter-spaces are only designed for use with SAMs.**
 
-Parameter spaces are implemented as subclasses of the |pspace_class| class, and are generally named with a ``PS_`` prefix.  Each class generates a certain number of samples using a latin hypercube to efficiently sample the parameter space.  Each parameter being varied in the parameter space corresponds to parameter distribution, implemented as a :py:class:`~holodeck.librarian.libraries._Param_Dist` subclass.  Each subclass is generally named with a ``PD_`` prefix.  These parameter distributions convert from uniform random variables (uniform samples in $[0.0, 1.0]$ in the latin hypercube) to the desired distributions.  For example, the :py:class:`~holodeck.librarian.libraries.PD_Normal(mean, stdev)` class draws from a normal (Gaussian) distribution, and the :py:class:`~holodeck.librarian.libraries.PD_Normal(min, max)` class draws from a uniform distribution.
+Parameter spaces are implemented as subclasses of the |pspace_class| class, and are generally named with a ``PS_`` prefix.  Each class generates a certain number of samples using a latin hypercube to efficiently sample the parameter space.  Each parameter being varied in the parameter space corresponds to parameter distribution, implemented as a :py:class:`~holodeck.librarian.lib_tools._Param_Dist` subclass.  Each subclass is generally named with a ``PD_`` prefix.  These parameter distributions convert from uniform random variables (uniform samples in $[0.0, 1.0]$ in the latin hypercube) to the desired distributions.  For example, the :py:class:`~holodeck.librarian.lib_tools.PD_Normal(mean, stdev)` class draws from a normal (Gaussian) distribution, and the :py:class:`~holodeck.librarian.lib_tools.PD_Normal(min, max)` class draws from a uniform distribution.
 
 Parameter Distributions
 -----------------------
 
-New parameter distributions should subclass :py:class:`~holodeck.librarian.libraries._Param_Dist`, and must provide a method with signature: ``_dist_func(self, xx)`` which accepts a float value ``xx`` in $[0.0, 1.0]$ and maps it to a value in the desired distribution, and returns a float value.  Typically an ``__init__`` function will also be provided to set any required parameters.  See the :py:class:`~holodeck.librarian.libraries.PD_Uniform` class for a simple example that maps from $[0.0, 1.0]$ to another uniform variable with a different minimum (``lo``) and maximum (``hi``) value.
+New parameter distributions should subclass :py:class:`~holodeck.librarian.lib_tools._Param_Dist`, and must provide a method with signature: ``_dist_func(self, xx)`` which accepts a float value ``xx`` in $[0.0, 1.0]$ and maps it to a value in the desired distribution, and returns a float value.  Typically an ``__init__`` function will also be provided to set any required parameters.  See the :py:class:`~holodeck.librarian.lib_tools.PD_Uniform` class for a simple example that maps from $[0.0, 1.0]$ to another uniform variable with a different minimum (``lo``) and maximum (``hi``) value.
 
-How the parameter distributions are used in parameter spaces is described below, but in summary, each |pspace_class| subclass will build a list of |pdist_class| subclass instances which are used to specify the domain of the parameter space.  The construct for each |pdist_class| subclass must accept first the variable name, and then any additional required arguments, for example: ``PD_Normal("gsmf_phi0", -2.56, 0.4)``.  The name of the variable **must match the name used in the |pspace_class|**, i.e. for the previous example, the |pspace_class| will be expecting a variable named ``gsmf_phi0``.  All |pdist_class| subclasses optionally accept a ``default=`` keyword-argument, for example, ``PD_Uniform("hard_time", 0.1, 11.0, default=3.0)``.  The 'default' values are provided so that |pspace_class|'s can construct a model using default parameters (see: :py:meth:`holodeck.librarian.libraries._Param_Space.default_params`), typically as a fiducial model.  In the preceding example, the default 'hard_time' parameter would be 3.0.  If a ``default`` is not specified in the instance constructor, then the value produced by an input of ``0.5`` is used.  In the preceding example, if no ``default`` was specified, then the middle value of $(11.0 + 0.1) / 2 = 5.55$ would be used.
+How the parameter distributions are used in parameter spaces is described below, but in summary, each |pspace_class| subclass will build a list of |pdist_class| subclass instances which are used to specify the domain of the parameter space.  The construct for each |pdist_class| subclass must accept first the variable name, and then any additional required arguments, for example: ``PD_Normal("gsmf_phi0", -2.56, 0.4)``.  The name of the variable **must match the name used in the |pspace_class|**, i.e. for the previous example, the |pspace_class| will be expecting a variable named ``gsmf_phi0``.  All |pdist_class| subclasses optionally accept a ``default=`` keyword-argument, for example, ``PD_Uniform("hard_time", 0.1, 11.0, default=3.0)``.  The 'default' values are provided so that |pspace_class|'s can construct a model using default parameters (see: :py:meth:`holodeck.librarian.lib_tools._Param_Space.default_params`), typically as a fiducial model.  In the preceding example, the default 'hard_time' parameter would be 3.0.  If a ``default`` is not specified in the instance constructor, then the value produced by an input of ``0.5`` is used.  In the preceding example, if no ``default`` was specified, then the middle value of $(11.0 + 0.1) / 2 = 5.55$ would be used.
 
 Parameter Spaces
 ----------------
@@ -41,9 +41,9 @@ Parameter spaces must subclass |pspace_class|, and provide 4 elements:
 
    * *|ps_test_class| Example:* while this example construct a 3-dimensional parameter space (over "hard_time", "hard_gamma_inner", "mmb_mamp"), there are ``DEFAULTS`` specified for all of the parameters used to construct the GSMF, GMR, M-MBulge, and hardening models.
 
-(1) An ``__init__()`` method that passes all required parameter distributions (:py:class:`~holodeck.librarian.libraries._Param_Dist` subclasses) to the super-class ``__init__()`` method.  The list of |pdist_class| instances is where the actual parameter-space being explored is defined.  Adding or removing a new element to this list of instances is all that it takes to increase or decrease the parameter space.
+(1) An ``__init__()`` method that passes all required parameter distributions (:py:class:`~holodeck.librarian.lib_tools._Param_Dist` subclasses) to the super-class ``__init__()`` method.  The list of |pdist_class| instances is where the actual parameter-space being explored is defined.  Adding or removing a new element to this list of instances is all that it takes to increase or decrease the parameter space.
 
-   * *|ps_test_class| Example:* in this case, a 3-dimensional parameter space is constructed, using uniform distributions (:py:class:`~holodeck.librarian.libraries.PD_Uniform`) for "hard_time" and "hard_gamma_inner", and a normal (i.e. Gaussian, :py:class:`~holodeck.librarian.libraries.PD_Normal`) distribution for "hard_time".
+   * *|ps_test_class| Example:* in this case, a 3-dimensional parameter space is constructed, using uniform distributions (:py:class:`~holodeck.librarian.lib_tools.PD_Uniform`) for "hard_time" and "hard_gamma_inner", and a normal (i.e. Gaussian, :py:class:`~holodeck.librarian.lib_tools.PD_Normal`) distribution for "hard_time".
 
 (2) An ``_init_sam()`` function that takes the input parameters, and then constructs and returns a |sam_class| instance.
 
@@ -92,9 +92,9 @@ Using holodeck libraries
 Loading a saved parameter-space instance
 ----------------------------------------
 
-TLDR: Use the :py:func:`~holodeck.librarian.libraries.load_pspace_from_path` function, passing in the path to the directory containing the save file (a ``.pspace.npz`` file).
+TLDR: Use the :py:func:`~holodeck.librarian.lib_tools.load_pspace_from_path` function, passing in the path to the directory containing the save file (a ``.pspace.npz`` file).
 
-Typically all that is needed for using/analyzing a holodeck library is the combined library output file ``sam_lib.hdf5``.  A saved instance of the parameter-space class which generated the library is also saved to the output directory (as a ``.pspace.npz`` file), and can be useful for some use cases, for example if new simulations/realizations are desired from the same parameter space.  The |pspace_class| provides a method to load saved instances, see the :py:meth:`~holodeck.librarian.libraries._Param_Space.from_save` method.  Typically, the best way to load a saved parameter-space instance is to use the :py:func:`~holodeck.librarian.libraries.load_pspace_from_path` function.
+Typically all that is needed for using/analyzing a holodeck library is the combined library output file ``sam_lib.hdf5``.  A saved instance of the parameter-space class which generated the library is also saved to the output directory (as a ``.pspace.npz`` file), and can be useful for some use cases, for example if new simulations/realizations are desired from the same parameter space.  The |pspace_class| provides a method to load saved instances, see the :py:meth:`~holodeck.librarian.lib_tools._Param_Space.from_save` method.  Typically, the best way to load a saved parameter-space instance is to use the :py:func:`~holodeck.librarian.lib_tools.load_pspace_from_path` function.
 
 The combined holodeck library file ``sam_lib.hdf5``
 ---------------------------------------------------

docs/source/header.rst

@@ -1,6 +1,6 @@
 .. |holodeck| replace:: :py:mod:`holodeck`
 .. |sam_class| replace:: :py:class:`~holodeck.sams.sam.Semi_Analytic_Model`
 .. |hard_class| replace:: :py:class:`~holodeck.hardening._Hardening`
-.. |pspace_class| replace:: :py:class:`~holodeck.librarian.libraries._Param_Space`
-.. |pdist_class| replace:: :py:class:`~holodeck.librarian.libraries._Param_Dist`
+.. |pspace_class| replace:: :py:class:`~holodeck.librarian.lib_tools._Param_Space`
+.. |pdist_class| replace:: :py:class:`~holodeck.librarian.lib_tools._Param_Dist`
 .. |ps_test_class| replace:: :py:class:`~holodeck.librarian.param_spaces.PS_Test`

holodeck/__init__.py

@@ -79,7 +79,10 @@ class Parameters:
 
 # NOTE: Must load and initialize cosmology before importing other submodules!
 import cosmopy   # noqa
-cosmo = cosmopy.Cosmology(h=Parameters.HubbleParam, Om0=Parameters.Omega0, Ob0=Parameters.OmegaBaryon)
+cosmo = cosmopy.Cosmology(
+    h=Parameters.HubbleParam, Om0=Parameters.Omega0, Ob0=Parameters.OmegaBaryon,
+    size=200,
+)
 del cosmopy
 
 # ---- Import submodules