Deprecate 'holodeck.librarian.libraries' ==> 'holodeck.librarian.lib_…

…tools'

CHANGELOG.md

@@ -19,19 +19,26 @@
 
 ## Current
 
-* 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.
+* 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`.
 
 * 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.
 
-* Semi-Analytic Models
-    * 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"
+* 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

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/librarian/__init__.py

@@ -4,10 +4,10 @@
 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.  Libraries are constructed
 using a 'parameter space' class that organizes the different simulations.  The base-class is
-:class:`~holodeck.librarian.libraries._Param_Space` (defined in the :mod:`holodeck.librarian.libraries`
+:class:`~holodeck.librarian.lib_tools._Param_Space` (defined in the :mod:`holodeck.librarian.lib_tools`
 file).  The parameter-space subclasses are given a number of different parameters to be 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
+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.
 
 For more information, see the :doc:`'libraries' page in the getting-started guide
@@ -18,9 +18,9 @@
 The ``librarian`` module is composed of the following elements:
 
 * The core components of the holodeck libraries are defined in
-  :py:mod:`~holodeck.librarian.libraries`.  Constructing simulations from parameter spaces can be
+  :py:mod:`~holodeck.librarian.lib_tools`.  Constructing simulations from parameter spaces can be
   performed using the relevant parameter spaces themselves (subclasses of
-  :py:class:`~holodeck.librarian.libraries._Param_Space`).
+  :py:class:`~holodeck.librarian.lib_tools._Param_Space`).
 
 * Parameter spaces are defined in the 'param_spaces' files, particularly:
 
@@ -39,6 +39,10 @@
 
 """
 
+# ==============================================================================
+# ==== Submodule Definitions ====
+# ==============================================================================
+
 __version__ = "1.2"
 
 DEF_NUM_REALS = 100     #: Default number of realizations to construct in libraries.
@@ -67,11 +71,18 @@ def __init__(self, message="This looks like a 'domain' not a 'library'!"):
         # Call the base class constructor with the parameters it needs
         super(DomainNotLibraryError, self).__init__(message)
 
-from . libraries import (      # noqa
-    _Param_Space, _Param_Dist,
-    PD_Uniform, PD_Normal,
-    run_model, load_pspace_from_path,
-)
+# ==============================================================================
+# ==== Import Submodule Components ====
+# ==============================================================================
+
+from . lib_tools import *    # noqa
+from . import gen_lib        # noqa
+
+# from . lib_tools import (      # noqa
+#     _Param_Space, _Param_Dist,
+#     PD_Uniform, PD_Normal,
+#     run_model, load_pspace_from_path,
+# )
 
 param_spaces_dict = {}    #: Registry of standard parameter-spaces
 from . import param_spaces_classic as psc_temp  # noqa