From 16a8bcf541a25733314e8e81c3c2c25c33e8be44 Mon Sep 17 00:00:00 2001 From: Luke Zoltan Kelley Date: Mon, 29 Apr 2024 11:22:23 -0700 Subject: [PATCH] Deprecate 'holodeck.librarian.libraries' ==> 'holodeck.librarian.lib_tools' --- CHANGELOG.md | 23 ++++++++----- ...s.rst => holodeck.librarian.lib_tools.rst} | 4 +-- docs/source/api_ref/holodeck.librarian.rst | 2 +- docs/source/getting_started/libraries.rst | 16 +++++----- docs/source/header.rst | 4 +-- holodeck/librarian/__init__.py | 31 ++++++++++++------ holodeck/librarian/combine.py | 10 +++--- holodeck/librarian/fit_spectra.py | 6 ++-- holodeck/librarian/gen_lib.py | 14 ++++---- .../librarian/{libraries.py => lib_tools.py} | 6 +++- holodeck/librarian/param_spaces.py | 2 +- holodeck/librarian/param_spaces_classic.py | 2 +- ...pace.py => test_lib_tools__param_space.py} | 8 ++--- holodeck/librarian/tests/test_param_spaces.py | 4 +-- notebooks/devs/libraries/gwb_anatomy.ipynb | 8 ++--- .../devs/libraries/library-explorer.ipynb | 4 +-- notebooks/devs/libraries/param_spaces.ipynb | 3 +- notebooks/librarian.ipynb | 32 +++++++++---------- 18 files changed, 100 insertions(+), 79 deletions(-) rename docs/source/api_ref/{holodeck.librarian.libraries.rst => holodeck.librarian.lib_tools.rst} (69%) rename holodeck/librarian/{libraries.py => lib_tools.py} (99%) rename holodeck/librarian/tests/{test_libraries__param_space.py => test_lib_tools__param_space.py} (97%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2d4387d6..d6b66d66 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/docs/source/api_ref/holodeck.librarian.libraries.rst b/docs/source/api_ref/holodeck.librarian.lib_tools.rst similarity index 69% rename from docs/source/api_ref/holodeck.librarian.libraries.rst rename to docs/source/api_ref/holodeck.librarian.lib_tools.rst index 69136318..160b12fe 100644 --- a/docs/source/api_ref/holodeck.librarian.libraries.rst +++ b/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: diff --git a/docs/source/api_ref/holodeck.librarian.rst b/docs/source/api_ref/holodeck.librarian.rst index 0ea4e99c..9ff9eb56 100644 --- a/docs/source/api_ref/holodeck.librarian.rst +++ b/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 diff --git a/docs/source/getting_started/libraries.rst b/docs/source/getting_started/libraries.rst index 235e8ec2..1ea61f15 100644 --- a/docs/source/getting_started/libraries.rst +++ b/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 ` 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`` --------------------------------------------------- diff --git a/docs/source/header.rst b/docs/source/header.rst index cc4f53da..09d800fb 100644 --- a/docs/source/header.rst +++ b/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` diff --git a/holodeck/librarian/__init__.py b/holodeck/librarian/__init__.py index 427bfdef..a98ce30e 100644 --- a/holodeck/librarian/__init__.py +++ b/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 diff --git a/holodeck/librarian/combine.py b/holodeck/librarian/combine.py index ede1a380..9d3c69b3 100644 --- a/holodeck/librarian/combine.py +++ b/holodeck/librarian/combine.py @@ -21,7 +21,7 @@ import holodeck.librarian import holodeck.librarian.gen_lib from holodeck.librarian import ( - libraries, DIRNAME_LIBRARY_SIMS, DIRNAME_DOMAIN_SIMS, DomainNotLibraryError + lib_tools, DIRNAME_LIBRARY_SIMS, DIRNAME_DOMAIN_SIMS, DomainNotLibraryError ) @@ -122,7 +122,7 @@ def sam_lib_combine( # ---- see if a combined library already exists - lib_path = libraries.get_sam_lib_fname(path_output, gwb_only) + lib_path = lib_tools.get_sam_lib_fname(path_output, gwb_only) if lib_path.exists(): lvl = log.INFO if recreate else log.WARNING log.log(lvl, f"combined library already exists: {lib_path}, run with `-r` to recreate.") @@ -135,7 +135,7 @@ def sam_lib_combine( if path_pspace is None: path_pspace = path_output - pspace, pspace_fname = libraries.load_pspace_from_path(path_pspace, log=log) + pspace, pspace_fname = lib_tools.load_pspace_from_path(path_pspace, log=log) args, args_fname = holo.librarian.gen_lib.load_config_from_path(path_pspace, log=log) log.info(f"loaded param space: {pspace} from '{pspace_fname}'") @@ -300,7 +300,7 @@ def _check_files_and_load_shapes(log, path_sims, nsamp, library): log.info(f"Checking {nsamp} files in {path_sims}") for ii in tqdm.trange(nsamp): - temp_fname = libraries._get_sim_fname(path_sims, ii, library=library) + temp_fname = lib_tools._get_sim_fname(path_sims, ii, library=library) if not temp_fname.exists(): err = f"Missing at least file number {ii} out of {nsamp} files! {temp_fname}" log.exception(err) @@ -396,7 +396,7 @@ def _load_library_from_all_files( bad_files = np.zeros(nsamp_all, dtype=bool) #: track which files contain UN-useable data msg = None for pnum in tqdm.trange(nsamp_all): - fname = libraries._get_sim_fname(path_sims, pnum, library=library) + fname = lib_tools._get_sim_fname(path_sims, pnum, library=library) temp = np.load(fname, allow_pickle=True) # When a processor fails for a given parameter, the output file is still created with the 'fail' key added if ('fail' in temp): diff --git a/holodeck/librarian/fit_spectra.py b/holodeck/librarian/fit_spectra.py index 4da08e60..e57f0432 100644 --- a/holodeck/librarian/fit_spectra.py +++ b/holodeck/librarian/fit_spectra.py @@ -43,7 +43,7 @@ import holodeck as holo import holodeck.librarian -from holodeck.librarian import libraries, FITS_NBINS_PLAW, FITS_NBINS_TURN +from holodeck.librarian import lib_tools, FITS_NBINS_PLAW, FITS_NBINS_TURN from holodeck.constants import YR @@ -108,7 +108,7 @@ def fit_library_spectra(library_path, log, recreate=False): library_path = Path(library_path) if library_path.is_dir(): - library_path = libraries.get_sam_lib_fname(library_path, gwb_only=False) + library_path = lib_tools.get_sam_lib_fname(library_path, gwb_only=False) if not library_path.exists() or not library_path.is_file(): err = f"{library_path=} must point to an existing library file!" log.exception(err) @@ -118,7 +118,7 @@ def fit_library_spectra(library_path, log, recreate=False): # ---- check for existing fits file - fits_path = libraries.get_fits_path(library_path) + fits_path = lib_tools.get_fits_path(library_path) return_flag = False if fits_path.exists(): lvl = log.INFO if recreate else log.WARNING diff --git a/holodeck/librarian/gen_lib.py b/holodeck/librarian/gen_lib.py index 48e8814d..57dcf84f 100644 --- a/holodeck/librarian/gen_lib.py +++ b/holodeck/librarian/gen_lib.py @@ -3,7 +3,7 @@ This file can be run from the command-line to generate holodeck libraries, and also provides some API methods for quick/easy generation of simulations. In general, these methods are designed to run simulations for populations constructed from parameter-spaces (i.e. -:class:`~holodeck.librarian.libraries._Param_Space` subclasses). This script is parallelized using +:class:`~holodeck.librarian.lib_tools._Param_Space` subclasses). This script is parallelized using ``mpi4py``, but can also be run in serial. This script can be run by executing:: @@ -35,7 +35,7 @@ import holodeck.librarian import holodeck.librarian.combine from holodeck.librarian import ( - libraries, ARGS_CONFIG_FNAME, PSPACE_DOMAIN_EXTREMA, DIRNAME_LIBRARY_SIMS, DIRNAME_DOMAIN_SIMS + lib_tools, ARGS_CONFIG_FNAME, PSPACE_DOMAIN_EXTREMA, DIRNAME_LIBRARY_SIMS, DIRNAME_DOMAIN_SIMS ) #: maximum number of failed simulations before task terminates with error (`None`: no limit) @@ -243,16 +243,16 @@ def run_sam_at_pspace_params(args, space, pnum, params): ``True``, otherwise the function runs this simulation. (2) Calls ``space.model_for_params`` to generate the semi-analytic model and hardening instances; see the function - :func:`holodeck.librarian.libraries._Param_Space.model_for_params()`. + :func:`holodeck.librarian.lib_tools._Param_Space.model_for_params()`. (3) Calculates populations and GW signatures from the SAM and hardening model using - :func:`holodeck.librarian.libraries.run_model()`, and saves the results to an output file. + :func:`holodeck.librarian.lib_tools.run_model()`, and saves the results to an output file. (4) Optionally: some diagnostic plots are created in the :func:`make_plots()` function. Arguments --------- args : ``argparse.ArgumentParser`` instance Arguments from the ``gen_lib_sams.py`` script. - space : :class:`holodeck.librarian.libraries._Param_space` instance + space : :class:`holodeck.librarian.lib_tools._Param_space` instance Parameter space from which to construct populations. pnum : int Which parameter-sample from ``space`` should be run. @@ -279,7 +279,7 @@ def run_sam_at_pspace_params(args, space, pnum, params): # ---- get output filename for this simulation, check if already exists library_flag = not args.domain - sim_fname = libraries._get_sim_fname(args.output_sims, pnum, library=library_flag) + sim_fname = lib_tools._get_sim_fname(args.output_sims, pnum, library=library_flag) beg = datetime.now() log.info(f"{pnum=} :: {sim_fname=} beginning at {beg}") @@ -301,7 +301,7 @@ def run_sam_at_pspace_params(args, space, pnum, params): log.debug("Selecting `sam` and `hard` instances") sam, hard = space.model_for_params(params) - data = libraries.run_model( + data = lib_tools.run_model( sam, hard, pta_dur=args.pta_dur, nfreqs=args.nfreqs, nreals=args.nreals, nloudest=args.nloudest, gwb_flag=args.gwb_flag, singles_flag=args.ss_flag, details_flag=False, params_flag=args.params_flag, diff --git a/holodeck/librarian/libraries.py b/holodeck/librarian/lib_tools.py similarity index 99% rename from holodeck/librarian/libraries.py rename to holodeck/librarian/lib_tools.py index b9261495..0042a6a1 100644 --- a/holodeck/librarian/libraries.py +++ b/holodeck/librarian/lib_tools.py @@ -26,6 +26,10 @@ "gsmf_phi0": ["gsmf_phi0_log10", None], } +# __all__ = [ +# "_Param_space" +# ] + class _Param_Space(abc.ABC): """Base class for generating holodeck libraries. Defines the parameter space and settings. @@ -60,7 +64,7 @@ def __init__(self, parameters, log=None, nsamples=None, sam_shape=None, seed=Non param_kwargs : dict Key-value pairs specifying the parameters for this model. Each key must be the name of the parameter, and each value must be a - :class:`~holodeck.librarian.libraries._Param_Dist` + :class:`~holodeck.librarian.lib_tools._Param_Dist` subclass instance with the desired distribution. Returns diff --git a/holodeck/librarian/param_spaces.py b/holodeck/librarian/param_spaces.py index cff7f5d3..74da3bd5 100644 --- a/holodeck/librarian/param_spaces.py +++ b/holodeck/librarian/param_spaces.py @@ -3,7 +3,7 @@ import holodeck as holo from holodeck.constants import GYR, PC, MSOL -from holodeck.librarian.libraries import _Param_Space, PD_Uniform, PD_Normal, PD_Uniform_Log +from holodeck.librarian.lib_tools import _Param_Space, PD_Uniform, PD_Normal, PD_Uniform_Log # Define a new Parameter-Space class by subclassing the base class: diff --git a/holodeck/librarian/param_spaces_classic.py b/holodeck/librarian/param_spaces_classic.py index 8e90e705..6f49331a 100644 --- a/holodeck/librarian/param_spaces_classic.py +++ b/holodeck/librarian/param_spaces_classic.py @@ -2,7 +2,7 @@ """ from holodeck.constants import PC, GYR -from holodeck.librarian.libraries import _Param_Space, PD_Uniform, PD_Normal +from holodeck.librarian.lib_tools import _Param_Space, PD_Uniform, PD_Normal from holodeck import sams, hardening, host_relations diff --git a/holodeck/librarian/tests/test_libraries__param_space.py b/holodeck/librarian/tests/test_lib_tools__param_space.py similarity index 97% rename from holodeck/librarian/tests/test_libraries__param_space.py rename to holodeck/librarian/tests/test_lib_tools__param_space.py index 57ef580f..7d037ccc 100644 --- a/holodeck/librarian/tests/test_libraries__param_space.py +++ b/holodeck/librarian/tests/test_lib_tools__param_space.py @@ -1,4 +1,4 @@ -"""Test holodeck/librarian/libraries.py: the parameter space base class, and parameter distributions. +"""Test holodeck/librarian/lib_tools.py: the parameter space base class, and parameter distributions. """ import numpy as np @@ -12,7 +12,7 @@ from holodeck.librarian import ( param_spaces_dict ) -from holodeck.librarian.libraries import ( +from holodeck.librarian.lib_tools import ( _Param_Space, PD_Uniform, ) @@ -205,8 +205,8 @@ def _check_sam_hard(sam, hard, sam_shape): assert isinstance(hard, hardening.Hard_GW) # Make sure model runs - import holodeck.librarian.libraries # noqa - data = librarian.libraries.run_model(sam, hard) + import holodeck.librarian.lib_tools # noqa + data = librarian.lib_tools.run_model(sam, hard) assert data is not None return diff --git a/holodeck/librarian/tests/test_param_spaces.py b/holodeck/librarian/tests/test_param_spaces.py index 9b6a15af..7c24f71c 100644 --- a/holodeck/librarian/tests/test_param_spaces.py +++ b/holodeck/librarian/tests/test_param_spaces.py @@ -14,8 +14,8 @@ def _run_param_space(param_space_class): # sam, hard = pspace.model_for_sample_number(0) sam, hard = pspace.model_for_params(pspace.default_params()) # Make sure model runs - import holodeck.librarian.libraries # noqa - data = librarian.libraries.run_model(sam, hard, singles_flag=True, details_flag=True) + import holodeck.librarian.lib_tools # noqa + data = librarian.lib_tools.run_model(sam, hard, singles_flag=True, details_flag=True) assert data is not None, "After `run_model` returned data is None!" check_keys = ['fobs_cents', 'fobs_edges', 'hc_ss', 'hc_bg', 'gwb', 'static_binary_density', 'number'] for key in check_keys: diff --git a/notebooks/devs/libraries/gwb_anatomy.ipynb b/notebooks/devs/libraries/gwb_anatomy.ipynb index 733c7334..a26ff37d 100644 --- a/notebooks/devs/libraries/gwb_anatomy.ipynb +++ b/notebooks/devs/libraries/gwb_anatomy.ipynb @@ -132,7 +132,7 @@ "outputs": [], "source": [ "import holodeck.librarian.old_param_spaces\n", - "import holodeck.librarian.libraries\n", + "import holodeck.librarian.lib_tools\n", "\n", "# construct a param_space instance, note that `nsamples` and `seed` don't matter here for how we'll use this\n", "pspace = holo.librarian.old_param_spaces.PS_Uniform_07B_Rot(holo.log, nsamples=1, sam_shape=SHAPE, seed=None)\n", @@ -148,7 +148,7 @@ "fiducial_parameters = pspace._normalized_params(fiducial_pars)\n", "fiducial_sam, fiducial_hard = pspace.model_for_params(fiducial_parameters, sam_shape=SHAPE) # <-- slow for some reason?\n", "#fiducial_sam, fiducial_hard = pspace.model_for_normalized_params(fiducial_pars)\n", - "fiducial_model_data = holo.librarian.libraries.run_model(fiducial_sam, fiducial_hard, nreals=NREALS, gwb_flag=True, details_flag=True) # Only run fiducial model once to save time!\n", + "fiducial_model_data = holo.librarian.lib_tools.run_model(fiducial_sam, fiducial_hard, nreals=NREALS, gwb_flag=True, details_flag=True) # Only run fiducial model once to save time!\n", "\n", "alldata = []\n", "allparams_list = {}\n", @@ -156,7 +156,7 @@ "fiducial_gwonly_hard = holo.hardening.Hard_GW()\n", "fiducial_sam.ZERO_DYNAMIC_STALLED_SYSTEMS = False\n", "fiducial_sam.ZERO_GMT_STALLED_SYSTEMS = True\n", - "fiducial_gwonly_model_data = holo.librarian.libraries.run_model(\n", + "fiducial_gwonly_model_data = holo.librarian.lib_tools.run_model(\n", " fiducial_sam, fiducial_gwonly_hard, nreals=NREALS, gwb_flag=True, details_flag=True\n", ")\n", "print(fiducial_gwonly_model_data.keys())\n", @@ -199,7 +199,7 @@ " # sam, hard = pspace.model_for_normalized_params(pars)\n", " sam, hard = pspace.model_for_params(parameters, sam_shape=SHAPE) # <-- slow for some reason?\n", " # run this model, retrieving binary parameters and the GWB\n", - " _data = holo.librarian.libraries.run_model(sam, hard, nreals=NREALS, gwb_flag=True, details_flag=True)\n", + " _data = holo.librarian.lib_tools.run_model(sam, hard, nreals=NREALS, gwb_flag=True, details_flag=True)\n", " data.append(_data)\n", " mingwb = np.min([mingwb, np.min(_data['gwb'])])\n", " maxgwb = np.max([mingwb, np.max(_data['gwb'])])\n", diff --git a/notebooks/devs/libraries/library-explorer.ipynb b/notebooks/devs/libraries/library-explorer.ipynb index fd377fa6..12444622 100644 --- a/notebooks/devs/libraries/library-explorer.ipynb +++ b/notebooks/devs/libraries/library-explorer.ipynb @@ -356,7 +356,7 @@ "CREATE = False\n", "RECREATE = False\n", "import holodeck.librarian.fit_spectra\n", - "fits_path = holo.librarian.libraries.get_fits_path(lib_path)\n", + "fits_path = holo.librarian.lib_tools.get_fits_path(lib_path)\n", "print(f\"{fits_path.name=} {fits_path.exists()=}\")\n", "if CREATE or RECREATE:\n", " if (CREATE and (not fits_path.exists())) or RECREATE:\n", @@ -1349,7 +1349,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.4" + "version": "3.11.7" }, "vscode": { "interpreter": { diff --git a/notebooks/devs/libraries/param_spaces.ipynb b/notebooks/devs/libraries/param_spaces.ipynb index a924be2e..fe108d2d 100644 --- a/notebooks/devs/libraries/param_spaces.ipynb +++ b/notebooks/devs/libraries/param_spaces.ipynb @@ -11,7 +11,6 @@ "\n", "import holodeck as holo\n", "from holodeck import librarian\n", - "import holodeck.librarian.libraries\n", "from holodeck.constants import MSOL, GYR, YR" ] }, @@ -35,7 +34,7 @@ "metadata": {}, "outputs": [], "source": [ - "data = librarian.libraries.run_model(sam, hard)" + "data = librarian.lib_tools.run_model(sam, hard)" ] }, { diff --git a/notebooks/librarian.ipynb b/notebooks/librarian.ipynb index c181a35e..bad0b716 100644 --- a/notebooks/librarian.ipynb +++ b/notebooks/librarian.ipynb @@ -48,7 +48,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Holodeck libraries are build around their parameter-spaces, which are implemented as subclasses of the [`holodeck.librarian.libraries._Param_Space`](https://holodeck-gw.readthedocs.io/en/main/api_ref/holodeck.librarian.libraries.html#holodeck.librarian.libraries._Param_Space) base class. These subclasses should be named with `PS_` prefixes to denote that they are parameter spaces." + "Holodeck libraries are build around their parameter-spaces, which are implemented as subclasses of the [`holodeck.librarian.lib_tools._Param_Space`](https://holodeck-gw.readthedocs.io/en/main/api_ref/holodeck.librarian.lib_tools.html#holodeck.librarian.lib_tools._Param_Space) base class. These subclasses should be named with `PS_` prefixes to denote that they are parameter spaces." ] }, { @@ -142,7 +142,7 @@ "metadata": {}, "outputs": [], "source": [ - "data = holo.librarian.libraries.run_model(sam, hard, details_flag=True)\n", + "data = holo.librarian.lib_tools.run_model(sam, hard, details_flag=True)\n", "print(data.keys())\n", "data['gwb']" ] @@ -161,13 +161,13 @@ "metadata": {}, "outputs": [], "source": [ - "class PS_Lib_Test(holo.librarian.libraries._Param_Space):\n", + "class PS_Lib_Test(holo.librarian.lib_tools._Param_Space):\n", "\n", " DEFAULTS = {'gsmf_phi0_log10': -2.77}\n", "\n", " def __init__(self, log, nsamples, sam_shape):\n", " parameters = [\n", - " holo.librarian.libraries.PD_Normal(\"gsmf_phi0_log10\", -2.77, 0.3),\n", + " holo.librarian.lib_tools.PD_Normal(\"gsmf_phi0_log10\", -2.77, 0.3),\n", " ]\n", " super().__init__(\n", " parameters,\n", @@ -215,7 +215,7 @@ "metadata": {}, "outputs": [], "source": [ - "test = holo.librarian.libraries.PD_Uniform(\"test\", -10.0, 10.0)\n", + "test = holo.librarian.lib_tools.PD_Uniform(\"test\", -10.0, 10.0)\n", "assert test(0.5) == 0.0\n", "assert test(0.0) == -10.0\n", "assert test(1.0) == +10.0\n", @@ -240,7 +240,7 @@ "metadata": {}, "outputs": [], "source": [ - "test = holo.librarian.libraries.PD_Normal(\"test\", 0.0, 1.0)\n", + "test = holo.librarian.lib_tools.PD_Normal(\"test\", 0.0, 1.0)\n", "val = test(0.5)\n", "print(val)\n", "assert test(0.5) == 0.0\n", @@ -265,7 +265,7 @@ "metadata": {}, "outputs": [], "source": [ - "test = holo.librarian.libraries.PD_Lin_Log(\"test\", 0.01, 100.0, 0.1, 0.5)\n", + "test = holo.librarian.lib_tools.PD_Lin_Log(\"test\", 0.01, 100.0, 0.1, 0.5)\n", "xx = np.linspace(0.0, 1.0, 10000)\n", "yy = test(xx)\n", "print(utils.minmax(yy))\n", @@ -300,7 +300,7 @@ "\n", "fig, ax = plot.figax(scale='log')\n", "for frac in [0.2, 0.5, 0.8]:\n", - " test = holo.librarian.libraries.PD_Lin_Log(\"test\", 0.01, 100.0, crit, frac)\n", + " test = holo.librarian.lib_tools.PD_Lin_Log(\"test\", 0.01, 100.0, crit, frac)\n", " xx = test(np.random.uniform(0.0, 1.0, size=NUM))\n", " kale.dist1d(xx, ax=ax, edges=edges, density=True, probability=False)\n", " obs_frac = np.count_nonzero(xx < crit) / xx.size\n", @@ -332,7 +332,7 @@ "\n", "fig, ax = plot.figax(scale='log')\n", "for crit in [0.1, 1.0, 10.0]:\n", - " test = holo.librarian.libraries.PD_Lin_Log(\"test\", 0.01, 100.0, crit, frac)\n", + " test = holo.librarian.lib_tools.PD_Lin_Log(\"test\", 0.01, 100.0, crit, frac)\n", " xx = test(np.random.uniform(0.0, 1.0, size=NUM))\n", " kale.dist1d(xx, ax=ax, edges=edges, density=True, probability=False)\n", " obs_frac = np.count_nonzero(xx < crit) / xx.size\n", @@ -356,7 +356,7 @@ "metadata": {}, "outputs": [], "source": [ - "test = holo.librarian.libraries.PD_Log_Lin(\"test\", 0.01, 100.0, 0.1, 0.5)\n", + "test = holo.librarian.lib_tools.PD_Log_Lin(\"test\", 0.01, 100.0, 0.1, 0.5)\n", "xx = np.linspace(0.0, 1.0, 10000)\n", "yy = test(xx)\n", "print(utils.minmax(yy))\n", @@ -389,7 +389,7 @@ "\n", "fig, ax = plot.figax(scale='log')\n", "for frac in [0.2, 0.5, 0.8]:\n", - " test = holo.librarian.libraries.PD_Log_Lin(\"test\", 0.01, 100.0, crit, frac)\n", + " test = holo.librarian.lib_tools.PD_Log_Lin(\"test\", 0.01, 100.0, crit, frac)\n", " xx = test(np.random.uniform(0.0, 1.0, size=NUM))\n", " kale.dist1d(xx, ax=ax, edges=edges, density=True, probability=False)\n", " obs_frac = np.count_nonzero(xx < crit) / xx.size\n", @@ -422,7 +422,7 @@ "\n", "fig, ax = plot.figax(scale='log')\n", "for crit in [0.1, 1.0, 10.0]:\n", - " test = holo.librarian.libraries.PD_Log_Lin(\"test\", 0.01, 100.0, crit, frac)\n", + " test = holo.librarian.lib_tools.PD_Log_Lin(\"test\", 0.01, 100.0, crit, frac)\n", " xx = test(np.random.uniform(0.0, 1.0, size=NUM))\n", " kale.dist1d(xx, ax=ax, edges=edges, density=True, probability=False)\n", " obs_frac = np.count_nonzero(xx < crit) / xx.size\n", @@ -448,7 +448,7 @@ "source": [ "edges = [-1.0, 5.0, 6.0, 7.0]\n", "amps = [1.0, 2.0, 1.0]\n", - "test = holodeck.librarian.libraries.PD_Piecewise_Uniform_Mass(\"test\", edges, amps)\n", + "test = holodeck.librarian.lib_tools.PD_Piecewise_Uniform_Mass(\"test\", edges, amps)\n", "\n", "xx = np.random.uniform(size=1000)\n", "xx = np.sort(xx)\n", @@ -466,7 +466,7 @@ "outputs": [], "source": [ "edges = [-1.0, 4.0, 6.0, 7.5]\n", - "test = holodeck.librarian.libraries.PD_Piecewise_Uniform_Density(\"test\", edges, [1.0, 2.0, 1.0])\n", + "test = holodeck.librarian.lib_tools.PD_Piecewise_Uniform_Density(\"test\", edges, [1.0, 2.0, 1.0])\n", "\n", "xx = np.random.uniform(size=1000)\n", "xx = np.sort(xx)\n", @@ -491,7 +491,7 @@ "outputs": [], "source": [ "edges = [0.1, 1.0, 9.0, 11.0]\n", - "test = holodeck.librarian.libraries.PD_Piecewise_Uniform_Density(\"test\", edges, [2.5, 0.5, 1.5])\n", + "test = holodeck.librarian.lib_tools.PD_Piecewise_Uniform_Density(\"test\", edges, [2.5, 0.5, 1.5])\n", "\n", "xx = np.random.uniform(size=2000)\n", "xx = np.sort(xx)\n", @@ -514,7 +514,7 @@ "metadata": {}, "outputs": [], "source": [ - "test = holodeck.librarian.libraries.PD_Piecewise_Uniform_Density(\n", + "test = holodeck.librarian.lib_tools.PD_Piecewise_Uniform_Density(\n", " \"test\", [7.5, 8.0, 9.0, 9.5], [1.5, 1.0, 2.0]\n", ")\n", "\n",