holodeck.librarian.gen_lib

Library generation interface.

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. _Param_Space subclasses).

This script can be run by executing:

python -m holodeck.librarian.gen_lib <ARGS>

Run python -m holodeck.librarian.gen_lib -h for usage information.

holodeck.librarian.gen_lib.main()

Parent method for generating libraries from the command-line.

This function requires mpi4py for parallelization.

This method does the following:

1. Loads arguments from the command-line (args, via _setup_argparse()).

   1. The output directory is created as needed, along with the sims/ and logs/ subdirectories in which the simulation datafiles and log output files are saved.

2. Sets up a logging.Logger instance for each processor.

3. Constructs the parameter space specified by args.param_space. If this run is being resumed, then the param-space is loaded from an existing save file in the output directory.

4. Samples from the parameter space are allocated to all processors.

5. Each processor iterates over it’s allocated parameters, calculates populations, saves them to files in the output directories. This is handled in run_sam_at_pspace_num().

6. All of the individual simulation files are combined using holodeck.librarian.combine.sam_lib_combine().

Parameters:

None –

Return type:

None

holodeck.librarian.gen_lib.run_sam_at_pspace_num(args, space, pnum)

Run a given simulation (index number pnum) in the space parameter-space.

This function performs the following:

1. Constructs the appropriate filename for this simulation, and checks if it already exist. If the file exists and the args.recreate option is not specified, the function returns True, otherwise the function runs this simulation.

2. Calls space.model_for_sample_number to generate the semi-analytic model and hardening instances; see the holodeck.librarian.params._Param_Space.model_for_sample_number() function.

3. Calculates populations and GW signatures from the SAM and hardening model using run_model(), and saves the results to an output file.

4. Optionally: some diagnostic plots are created in the make_plots() function.

Parameters:

• args (argparse.ArgumentParser instance) – Arguments from the gen_lib_sams.py script. NOTE: this should be improved.

• space (holodeck.librarian.params._Param_space instance) – Parameter space from which to construct populations.

• pnum (int) – Which parameter-sample from space should be run.

Returns:

• rv (bool) – True if this simulation was successfully run, False otherwise.

• sim_fname (pathlib.Path instance) – Path of the simulation save file.

holodeck.librarian.gen_lib.run_model(sam, hard, pta_dur=16.03, nfreqs=40, nreals=100, nloudest=5, gwb_flag=True, details_flag=False, singles_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.gen_lib._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.gen_lib._setup_argparse(*args, **kwargs)

Setup the argument-parser for command-line usage.

Parameters:

• *args (arguments) –

• **kwargs (keyword arguments) –

holodeck.librarian.gen_lib._setup_log(comm, args)

Setup up the logging module logger for output messaging.

Arguemnts

comm args

returns:

log

rtype:

logging.Logger instance

holodeck.librarian.gen_lib.make_plots(args, data, sim_fname)

Generate diagnostic plots from the given simulation data and save to file.

holodeck.librarian.gen_lib.make_gwb_plot(fobs, gwb, fit_data)

Generate a GWB plot from the given data.

holodeck.librarian.gen_lib.make_ss_plot(fobs, hc_ss, hc_bg, fit_data)

holodeck.librarian.gen_lib.make_pars_plot(fobs, hc_ss, hc_bg, sspar, bgpar)

Plot total mass, mass ratio, initial d_c, final d_c