Skip to content

Commit

Permalink
Merge branch 'dev-pspace-domains' of github.com:nanograv/holodeck int…
Browse files Browse the repository at this point in the history
…o dev-pspace-domains

* 'dev-pspace-domains' of github.com:nanograv/holodeck:
  Deprecate 'holodeck.librarian.libraries' ==> 'holodeck.librarian.lib_tools'
  • Loading branch information
lzkelley committed Apr 30, 2024
2 parents a19531f + 16a8bcf commit fa4fd75
Show file tree
Hide file tree
Showing 18 changed files with 100 additions and 79 deletions.
23 changes: 15 additions & 8 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
@@ -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:
Expand Down
2 changes: 1 addition & 1 deletion docs/source/api_ref/holodeck.librarian.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
16 changes: 8 additions & 8 deletions docs/source/getting_started/libraries.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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
----------------
Expand All @@ -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.

Expand Down Expand Up @@ -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``
---------------------------------------------------
Expand Down
4 changes: 2 additions & 2 deletions docs/source/header.rst
Original file line number Diff line number Diff line change
@@ -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`
31 changes: 21 additions & 10 deletions holodeck/librarian/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
Expand All @@ -39,6 +39,10 @@
"""

# ==============================================================================
# ==== Submodule Definitions ====
# ==============================================================================

__version__ = "1.2"

DEF_NUM_REALS = 100 #: Default number of realizations to construct in libraries.
Expand Down Expand Up @@ -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
Expand Down
Loading

0 comments on commit fa4fd75

Please sign in to comment.