holodeck.librarian.libraries

Parameters and parameter spaces for holodeck libraries.

class holodeck.librarian.libraries._Param_Space(parameters, log=None, nsamples=None, sam_shape=None, seed=None, random_state=None)

Bases: ABC

Base class for generating holodeck libraries. Defines the parameter space and settings.

Libraries are generated over some parameter space defined by which parameters are being varied.

_SAVED_ATTRIBUTES = ['sam_shape', 'param_names', '_uniform_samples', 'param_samples', '_nsamples', '_nparameters']

DEFAULTS = {}

model_for_params(params, sam_shape=None)

Construct a model (SAM and hardening instances) from the given parameters.

Parameters:

• params (dict) – Key-value pairs for sam/hardening parameters. Each item much match expected parameters that are set in the defaults dictionary.

• sam_shape (None or int or (3,) int) –

Returns:

• sam (holodeck.sam.Semi_Analytic_Model instance)

• hard (holodeck.hardening._Hardening instance)

abstract classmethod _init_sam(sam_shape, params)

abstract classmethod _init_hard(sam, params)

save(path_output)

Save the generated samples and parameter-space info from this instance to an output file.

This data can then be loaded using the _Param_Space.from_save method. NOTE: existing save files with the same name will be overwritten!

Parameters:

path_output (str) – Path in which to save file. This must be an existing directory.

Returns:

fname – Output path including filename in which this parameter-space was saved.

Return type:

pathlib.Path object

classmethod from_save(fname, log=None)

Create a new _Param_Space instance loaded from the given save file.

Parameters:

fname (str) – Filename containing parameter-space save information, generated form _Param_Space.save.

Returns:

space

Return type:

_Param_Space subclass instance

param_dict(samp_num)

property extrema

property name

property lib_shape

property nsamples

property nparameters

model_for_sample_number(samp_num, sam_shape=None)

normalized_params(vals)

Convert input values (uniform/linear) into parameters from the stored distributions.

For example, if this parameter space has 2 dimensions, where the distributions are:

0. ‘value_a’ is a uniform parameter from [-1.0, 1.0], and

1. ‘value_b’ normal with mean 10.0 and stdev 1.0

Then input values of [0.75, 0.5] are mapped to parameters [0.5, 10.0], which will be returned as {value_a: 0.5, value_b: 10.0}.

Parameters:

vals ((P,) iterable of float,) – A list/iterable of P float values, matching the number of parameters (i.e. dimensions) in this parameter space. Each value is passed to the corresponding distribution for that parameter.

Returns:

params – The resulting parameters in the form of key-value pairs where the keys are the parameter names, and the values are drawn from the correspinding distributions.

Return type:

dict,

default_params()

Return a parameter dictionary with default values for each parameter.

Returns:

params – Key-value pairs where each key is the parameter name, and the value is the default value returned from the _Param_Dist subclass.

Return type:

dict,

_abc_impl = <_abc._abc_data object>

class holodeck.librarian.libraries._Param_Dist(name, default=None, clip=None)

Bases: ABC

Parameter Distribution base-class for use in Latin HyperCube sampling.

These classes are passed uniform random variables between [0.0, 1.0], and return parameters from the desired distribution.

Subclasses are required to implement the _dist_func() function which accepts a float value from [0.0, 1.0] and returns the appropriate corresponding parameter, drawn from the desired distribution. In practice, _dist_func() is usually the inverse cumulative-distribution for the desired distribution function.

abstract _dist_func(*args, **kwargs)

property extrema

property name

property default

Return the default parameter value.

If a fixed value was set, it will be returned. Otherwise the parameter value for a random uniform input value of 0.5 will be returned.

_abc_impl = <_abc._abc_data object>

class holodeck.librarian.libraries.PD_Uniform(name, lo, hi, **kwargs)

Bases: _Param_Dist

_dist_func(xx)

_abc_impl = <_abc._abc_data object>

class holodeck.librarian.libraries.PD_Uniform_Log(name, lo, hi, **kwargs)

Bases: _Param_Dist

_dist_func(xx)

_abc_impl = <_abc._abc_data object>

class holodeck.librarian.libraries.PD_Normal(name, mean, stdev, clip=None, **kwargs)

Bases: _Param_Dist

Normal/Gaussian parameter distribution with given mean and standard-deviation.

NOTE: use clip parameter to avoid extreme values.

_dist_func(xx)

_abc_impl = <_abc._abc_data object>

class holodeck.librarian.libraries.PD_Lin_Log(name, lo, hi, crit, lofrac, **kwargs)

Bases: _Param_Dist

_dist_func(xx)

_abc_impl = <_abc._abc_data object>

class holodeck.librarian.libraries.PD_Log_Lin(name, lo, hi, crit, lofrac, **kwargs)

Bases: _Param_Dist

_dist_func(xx)

_abc_impl = <_abc._abc_data object>

class holodeck.librarian.libraries.PD_Piecewise_Uniform_Mass(name, edges, weights, **kwargs)

Bases: _Param_Dist

_dist_func(xx)

_abc_impl = <_abc._abc_data object>

class holodeck.librarian.libraries.PD_Piecewise_Uniform_Density(name, edges, densities, **kwargs)

Bases: PD_Piecewise_Uniform_Mass

_abc_impl = <_abc._abc_data object>

holodeck.librarian.libraries.run_model(sam, hard, pta_dur=16.03, nfreqs=40, nreals=100, nloudest=5, gwb_flag=True, singles_flag=True, details_flag=False, params_flag=False, log=None)

Run the given SAM and hardening model to construct a binary population and GW signatures.

Parameters:

• sam (holodeck.sams.sam.Semi_Analytic_Model instance,) –

• hard (holodeck.hardening._Hardening subclass instance,) –

• pta_dur (float, [seconds]) – Duration of PTA observations in seconds, used to determine Nyquist frequency basis at which GW signatures are calculated.

• nfreqs (int) – Number of Nyquist frequency bins at which to calculate GW signatures.

• nreals (int) – Number of ‘realizations’ (populations drawn from Poisson distributions) to construct.

• nloudest (int) – Number of loudest binaries to consider in each frequency bin. These are the highest GW strain binaries in each frequency bin, for which the individual source strains are calculated.

• gwb_flag –

• details_flag –

• singles_flag –

• params_flag –

• log (logging.Logger instance) –

Returns:

data – The population and GW data calculated from the simulation. The dictionary elements are:

• fobs_cents : Nyquist frequency bin centers, in units of [seconds].

• fobs_edges : Nyquist frequency bin edgeds, in units of [seconds].

• If details_flag == True:

  • static_binary_density :

  • number :

  • redz_final :

  • gwb_params :

  • num_params :

  • gwb_mtot_redz_final :

  • num_mtot_redz_final :

• If params_flag == True:

  • sspar :

  • bgpar :

• If singles_flag == True:

  • hc_ss :

  • hc_bg :

• If gwb_flag == True:

  • gwb :

Return type:

dict

holodeck.librarian.libraries._calc_model_details(edges, redz_final, number)

Calculate derived properties from the given populations.

Parameters:

• edges ((4,) list of 1darrays) – [mtot, mrat, redz, fobs_orb_edges] with shapes (M, Q, Z, F+1)

• redz_final ((M,Q,Z,F)) – Redshift final (redshift at the given frequencies).

• number ((M-1, Q-1, Z-1, F)) – Absolute number of binaries in the given bin (dimensionless).

Returns:

• gwb_pars

• num_pars

• gwb_mtot_redz_final

• num_mtot_redz_final

holodeck.librarian.libraries.load_pspace_from_path(path, space_class=None, log=None)

Load a _Param_Space subclass instance from the saved file in the given directory.

This function tries to determine the correct class based on the save file name, then uses that class to load the save itself.

Parameters:

• path (str or pathlib.Path) – Path to directory containing save file. A single file matching *.pspace.npz is required in that directory. NOTE: the specific glob pattern is specified by holodeck.librarian.PSPACE_FILE_SUFFIX e.g. ‘.pspace.npz’

• space_class (_Param_Space subclass or None) – Class with which to call the from_save() method to load a new _Param_Space instance. If None is given, then the filename is used to try to determine the appropriate class.

• log (logging.Logger) –

Returns:

• space (_Param_Space subclass instance) – An instance of the space_class class.

• space_fname (pathlib.Path) – File that space was loaded from.

holodeck.librarian.libraries._get_space_class_from_space_fname(space_fname)

holodeck.librarian.libraries._get_sim_fname(path, pnum)

holodeck.librarian.libraries.get_sam_lib_fname(path, gwb_only)

holodeck.librarian.libraries.get_fits_path(library_path)

Get the name of the spectral fits file, given a library file path.

holodeck.librarian.libraries.log_mem_usage(log)