posydon.popsyn

posydon.popsyn.GRB

posydon.popsyn.GRB.get_GRB_properties(df, GRB_efficiency, GRB_beaming, E_GRB_iso_min=0.)

Compute GRB properties for a given binary population.

posydon.popsyn.analysis

Module for analyzing binary population simulation results.

posydon.popsyn.analysis.get_subsets(path, find_n=None, select_oneline=None, select_history=None, select_columns=None, verbose=True)

Get the oneline and history subsets for a selection of binaries.

You select binaries from an HDF5 population by providing a function that operates either on oneline or history and returns a boolean mask in- dicating which rows correspond to the binaries of interest. E.g.,

def find_no_end(df):

return df[“event_f”] != “END”

can be used to find binaries that ended abruptly, based on the information in the oneline table. Therefore, we set select_oneline=find_no_end. If no selector has been set, all binaries are selected (combine this with the select_columns argument to get a column subset of the data.)

Parameters:

• path (str) – The fullpath of the HDF5 file.

• find_n (int or None) – The number of binaries to select (at most) or None to select all.

• select_oneline (function or None) – The function to operate on chunks of the oneline table.

• select_history (function or None) – The function to operate on chunks of the oneline table.

• select_columns (None or str or array) – If None, all columns will be returned. If a string, only those columns with name containing this string will be returned. An array of strings can be used for multiple such patterns.

Returns:

The subsets of the dataframes with the data for the selected binaries.

Return type:

oneline, history

posydon.popsyn.analysis.report_columns(path)

Print the columns in the oneline and history keys in an HDF5 file.

Parameters:

path (str) – The fullpath of the HDF5 file.

posydon.popsyn.binarypopulation

Create, evolve and save a binary star population.

Large populations are RAM limited when holding an arbitrary number of BinaryStar instances. Therefore, by default the BinaryPopulation will generate binaries, evolve, and try to save them to disk one at a time.

Create a BinaryPopulation instance from an inifile: I. CREATING A POPULATION ———————— a) One-liner for creating a BinaryPopulation from an inifile:

> BinaryPopulation.from_ini(‘<PATH_TO_POSYDON>’ ‘/posydon/popsyn/population_params_default.ini’)

class posydon.popsyn.binarypopulation.BinaryGenerator(sampler=generate_independent_samples, RNG=None, **kwargs)

Bases: object

Generate binaries to be included in a BinaryPopulation.

Initialize the BinaryGenerator instance.

draw_initial_binary(**kwargs)

Return a binary for evolution in a population.

Parameters:

index (int) – Sets binary index. Defaults to number of generated binaries.

Returns:

binary

Return type:

BinaryStar

draw_initial_samples(orbital_scheme='separation', **kwargs)

Generate all random varibles.

get_binary_by_iter(n=1, **kwargs)

Get the nth binary as if n calls were made to draw_intial_binary.

get_original_rng()

Return the random-number generator.

reset_rng()

Reset the RNG with the stored entropy.

class posydon.popsyn.binarypopulation.BinaryPopulation(**kwargs)

Bases: object

Handle a binary star population.

Initialize the binary population object.

Parameters:

• number_of_binaries (int) – Size of the population

• population_properties (SimulationProperties) – Instance of simulationproperties holding steps.

close()

Close loaded h5 files from SimulationProperties.

combine_saved_files(absolute_filepath, file_names, **kwargs)

Combine various temporary files in a given folder.

Parameters:

• absolute_filepath (str) – Absolute path to the file to be saved.

• file_names (list) – List of absolute paths to the temporary files.

evolve(**kwargs)

Evolve a binary population.

Parameters:

• indices (list, optional) – Custom binary indices to use. Default is range(number_of_binaries). If running with MPI, indices are split between processes if given.

• breakdown_to_df (bool, True) – Breakdown a binary after evolution, converting to dataframe and removing the binary instance from memory.

• tqdm (bool, False) – Show tqdm progress bar during evolution.

Return type:

None

classmethod from_ini(path, verbose=False)

Create a BinaryPopulation instance from an inifile.

Parameters:

• path (str) – Path to an inifile to load in.

• verbose (bool) – Print useful info.

Returns:

A new instance of a BinaryPopulation.

Return type:

BinaryPopulation

make_temp_fname()

Get a valid filename for the temporary file.

save(save_path, **kwargs)

Save BinaryPopulation to hdf file.

class posydon.popsyn.binarypopulation.PopulationManager(file_name=None, **kwargs)

Bases: object

Manage a population of binaries.

Initialize a PopulationManager instance.

append(binary)

Add a binary instance internaly.

breakdown_to_df(binary, **kwargs)

Breakdown to a pandas DataFrame.

Breakdown a binary into more convenient data type, store it, and remove the BinaryStar instance from self.

clear_dfs()

Remove all dfs.

close()

Close the HDF5 file.

find_failed()

Find any failed binaries in the population.

from_hdf(indices, where=None, restore=False)

Load a BinaryStar instance from an hdf file of a saved population.

Parameters:

• indices (int, list) – Selects the binaries to load.

• where (str) – Query performed on disk to select history and oneline DataFrames.

• restore (bool) – Restore binaries back to initial conditions.

generate(**kwargs)

Generate a binary by drawing from the binary_generator.

This can be a callable or a generator.

remove(binary)

Remove a binary instance.

save(fname, **kwargs)

Save binaries to an hdf file using pandas HDFStore.

Any object dtype columns not parsed by infer_objects() is converted to a string.

Parameters:

• fname (str) – Name of hdf file saved.

• mode ({'a', 'w', 'r', 'r+'}, default 'a') – See pandas HDFStore docs

• complib ({'zlib', 'lzo', 'bzip2', 'blosc'}, default 'zlib') – Compression library. See HDFStore docs

• complevel (int, 0-9, default 9) – Level of compression. See HDFStore docs

• kwargs (dict) – Arguments for BinaryStar methods to_df and to_oneline_df.

Return type:

None

to_df(selection_function=None, **kwargs)

Convert all binaries to dataframe.

to_oneline_df(selection_function=None, **kwargs)

Convert all binaries to oneline dataframe.

posydon.popsyn.defaults

Default binary population parameters.

posydon.popsyn.independent_sample

Generate the initial parameters for a binary population.

posydon.popsyn.independent_sample.binary_fraction_value(binary_fraction_const=1, binary_fraction_scheme='const', m1=None, **kwargs)

Getting the binary fraction depending on the scheme. The two possible option are a constant binary fraction and a binary fraction based on the values given in Moe and Di Stefano (2017).

posydon.popsyn.independent_sample.generate_eccentricities(number_of_binaries=1, eccentricity_scheme='thermal', **kwargs)

Generate random eccentricities.

Use the scheme defined in this particular instance of BinaryPopulation.

Parameters:

• number_of_binaries (int) – Number of binaries that require randomly sampled orbital separations

• eccentricity_scheme (string) – Distribution from which eccentricities are randomly drawn

• **kwargs (dictionary) – kwargs from BinaryPopulation class

Returns:

eccentricities – Randomly drawn eccentricities

Return type:

ndarray of floats

posydon.popsyn.independent_sample.generate_independent_samples(orbital_scheme, **kwargs)

Randomly generate a population of binaries at ZAMS.

Parameters:

• number_of_binaries (int) – Number of binaries that require randomly sampled orbital separations

• **kwargs (dictionary) – kwargs from BinaryPopulation class

Returns:

• orbital_scheme_set (ndarray of floats) – Randomly drawn orbital separations/periods depending on the scheme

• eccentricity_set (ndarray of floats) – Randomly drawn eccentricities

• m1_set (ndarray of floats) – Randomly drawn primary masses

• m2_set (ndarray of floats) – Randomly drawn secondary masses

posydon.popsyn.independent_sample.generate_orbital_periods(primary_masses, number_of_binaries=1, orbital_period_min=0.35, orbital_period_max=10**3.5, orbital_period_scheme='Sana+12_period_extended', **kwargs)

Randomaly generate orbital periods for a sample of binaries.

posydon.popsyn.independent_sample.generate_orbital_separations(number_of_binaries=1, orbital_separation_min=5, orbital_separation_max=1e5, log_orbital_separation_mean=None, log_orbital_separation_sigma=None, orbital_separation_scheme='log_uniform', **kwargs)

Generate random orbital separations.

Use the scheme defined in this particular instance of BinaryPopulation.

Parameters:

• number_of_binaries (int) – Number of binaries that require randomly sampled orbital separations

• orbital_separation_min (float) – Minimum orbital separation in solar radii

• orbital_separation_max (float) – Maximum orbital separation in solar radii

• log_orbital_separation_mean (float) – Mean of the lognormal distribution.

• log_orbital_separation_sigma (float) – Standard deviation of the lorgnormal distribution.

• orbital_separation_scheme (string) – Distribution from which the orbital separations are randomly drawn

Returns:

orbital_separations – Randomly drawn orbital separations

Return type:

ndarray of floats

posydon.popsyn.independent_sample.generate_primary_masses(number_of_binaries=1, primary_mass_min=7, primary_mass_max=120, primary_mass_scheme='Salpeter', **kwargs)

Generate random primary masses.

Use the scheme defined in this particular instance of BinaryPopulation.

Parameters:

• number_of_binaries (int) – Number of binaries that require randomly sampled orbital separations

• primary_mass_min (float) – Minimum primary mass

• primary_mass_max (float) – Maximum primary mass

• primary_mass_scheme (string) – Distribution from which the primary masses are randomly drawn

Returns:

primary_masses – Randomly drawn primary masses

Return type:

ndarray of floats

posydon.popsyn.independent_sample.generate_secondary_masses(primary_masses, number_of_binaries=1, secondary_mass_min=0.35, secondary_mass_max=120, secondary_mass_scheme='flat_mass_ratio', **kwargs)

Generate random secondary masses.

Use the scheme defined in this particular instance of BinaryPopulation.

Parameters:

• primary_masses (ndarray of floats) – Previously drawn primary masses

• number_of_binaries (int) – Number of binaries that require randomly sampled orbital separations

• secondary_mass_min (float) – Minimum secondary mass

• secondary_mass_max (float) – Maximum secondary mass

• secondary_mass_scheme (string) – Distribution from which the secondary masses are randomly drawn

Returns:

secondary_masses – Randomly drawn secondary masses

Return type:

ndarray of floats

posydon.popsyn.io

Handle I/O operations for the population synthesis code.

posydon.popsyn.io.binarypop_kwargs_from_ini(path, verbose=False)

Convert an inifile into kwargs for the BinaryPopulation class.

Parameters:

• path (str or list like) – Path to inifile. If multiple files are given, duplicate args are overwritten (stacked) first to last.

• verbose (bool) – Print helpful info.

Returns:

parser_dict – The inifile converted to the kwargs.

Return type:

<class, dict>

posydon.popsyn.io.clean_binary_history_df(binary_df, extra_binary_dtypes_user=None, extra_S1_dtypes_user=None, extra_S2_dtypes_user=None)

Take a posydon binary history DataFrame from the BinaryStar.to_df method and clean the data for saving by setting Data Types of the columns explicitly.

Parameters:

• binary_df (DataFrame) – A pandas Dataframe containing binary history

• extra_binary_dtypes_user (dict, optional) – A dictionary with extra column names as keys, and their associated data types as values.

• extra_S1_dtypes_user (dict, optional) – Same as above, but only for star 1.

• extra_S2_dtypes_user (dict, optional) – Same as above, but only for star 2.

Returns:

binary_df – A cleaned binary history ready for saving to HDF.

Return type:

DataFrame

posydon.popsyn.io.clean_binary_oneline_df(oneline_df, extra_binary_dtypes_user=None, extra_S1_dtypes_user=None, extra_S2_dtypes_user=None)

Take a posydon binary oneline DataFrame from the BinaryStar.to_oneline_df method and clean the data for saving by setting Data Types of the columns explicitly.

This method is similar to clean_binary_history_df since they have many overalapping columns, with a few extras and different naming.

Note: there may be edge cases not handed if new scalar_names are added.

Parameters:

• binary_df (DataFrame) – A pandas Dataframe containing binary history

• extra_binary_dtypes_user (dict, optional) – A dictionary with extra column names as keys, and their associated data types as values.

• extra_S1_dtypes_user (dict, optional) – Same as above, but only for star 1.

• extra_S2_dtypes_user (dict, optional) – Same as above, but only for star 2.

Returns:

binary_df – A cleaned binary history ready for saving to HDF.

Return type:

DataFrame

posydon.popsyn.io.parse_inifile(path, verbose=False)

Parse an inifile for evolving binary populations.

Parameters:

• path (str or list like) – Path to inifile. If multiple files are given, duplicate args are overwritten (stacked) first to last.

• verbose (bool) – Print helpful info.

Returns:

parser – An instance of ConfigParser.

Return type:

<class, ConfigParser>

posydon.popsyn.io.simprop_kwargs_from_ini(path, verbose=False)

Convert an inifile into kwargs for the SimulationProperties class.

Parameters:

• path (str or list like) – Path to inifile. If multiple files are given, duplicate args are overwritten (stacked) first to last.

• verbose (bool) – Print helpful info.

Returns:

parser_dict – The inifile converted to the kwargs.

Return type:

<class, dict>

posydon.popsyn.normalized_pop_mass

Compute the underlying stellar population mass for a given simulation.

posydon.popsyn.normalized_pop_mass.initial_total_underlying_mass(df=None, **kwargs)

Compute the initial total mass of the population.

Parameters:

• df (DataFrame) – Data frame of a population class. If nothing is provided the code will sample initial conditions.

• primary_mass_min (type) – Description of parameter primary_mass_min.

• primary_mass_max (type) – Description of parameter primary_mass_max.

• primary_mass_scheme (type) – Description of parameter primary_mass_scheme.

• secondary_mass_scheme (type) – Description of parameter secondary_mass_scheme.

• **kwargs (type) – Description of parameter **kwargs.

Returns:

Description of returned object.

Return type:

type

posydon.popsyn.rate_calculation

class posydon.popsyn.rate_calculation.Rates(df, verbose=False, **kwargs)

Bases: object

Compute DCO rates.

Compute DCO rates.

Parameters:

• df (object) – Pandas dataframe containing the synthetic binary population.

• delta_t (float) – Cosmic time bin size used to bin distribute the synthetc binary population.

• SFR (string) – Star-formation-rate history you want to use: ‘Madau+Dickinson14’, ‘Madau+Fragos17’, ‘Neijssel+19’, ‘IllustrisTNG’

• sigma_SFR (string) – Standard deviation of the trucated log-normal metallicity distribution assumed for the star-formation rate history in the case you select ‘Madau+Dickinson14’, ‘Madau+Fragos17’, ‘Neijssel+19’,

• Z_max (float) – The absolute maximum metallicity of the star formation rate history. NOTE: This should be used when assuming a truncated log-normal distribution of metallcities to not overpredict 1, also it can be used with the IllustrisTNG SFR to prevent unphysically high metallicities.

• select_one_met (bool) – If True your synthetic binary population should contain only one descrete metallicity.

• dlogZ (float or range) – Used when select_one_met=True to select the metallicity range around which you want to integrate the SFR history. If float value value is provided we assume a symmetric range dlogZ/2 around the provided metallcity else we consider the range provided [Z_min, Z_max] which could also be asymmetric.

• verbose (bool) – True if you want the print statements.

TODO: add the definitios of the variables used by this class.

chi_eff(m_1, m_2, a_1, a_2, tilt_1, tilt_2)

compute_GRB_rate_weights(sensitivity='infinity', path_to_dir='./', extention='npz')

Compute the cosmological weights of the transient events associated to the population.

This function will create a directory path_to_dir/GRBs/sensitivity where it will save the weigths, binary indicies k, z_formation, z_grb. This is needed for scalability as a ~100k DCO population generates ~10M non-zero weights assuming a delta_t=100Myr.

Parameters:

• sensitivity (string) – Assume there are no selection effects. Available: ‘infinite’: whole GRB population, i.e. p_det = 1

• path_to_dir (string) – Path to the workingn directory where you want to store the cosmological weights.

compute_merger_rate_weights(sensitivity, flag_pdet=True, path_to_dir='./', extention='npz')

Compute the cosmological weights of the DCO population.

This function will create a directory path_to_dir/DCOs/sensitivity where it will save the weigths, binary indicies k, z_formation, z_merger. This is needed for scalability as a ~100k DCO population generates ~10M non-zero weights assuming a delta_t=100Myr.

Parameters:

• sensitivity (string) –

  GW detector sensitivity and network configuration you want to use, see arXiv:1304.0670v3 detector sensitivities are taken from: https://dcc.ligo.org/LIGO-T2000012-v2/public available sensitivity keys (for Hanford, Livingston, Virgo network):

  ’O3actual_H1L1V1’ : aligo_O3actual_H1.txt, aligo_O3actual_L1.txt, avirgo_O3actual.txt ‘O4low_H1L1V1’ : aligo_O4low.txt, aligo_O4low.txt, avirgo_O4high_NEW.txt ‘O4high_H1L1V1’ : aligo_O4high.txt, aligo_O4high.txt, avirgo_O4high_NEW.txt ‘design_H1L1V1’ : AplusDesign.txt, AplusDesign.txt, avirgo_O5high_NEW.txt ‘infinite’: intrinsic merging DCO population, i.e. p_det = 1

• flag_pdet (bool) – This is a control variable. In order to be sure you want to run infinite sensitivity set p_det=False.

• path_to_dir (string) – Path to the workingn directory where you want to store the cosmological weights.

compute_rate_density(w_ijk, z_event, observable='DCO', sensitivity='infinite', index=None)

Compute the GRB/DCO rate density.

Parameters:

• w_ijk (array doubles) – Cosmological weights computed with Eq. B.8 of Bavera et at. (2020).

• z_event (array doubles) – Cosmolgocial redshift of the event you are tracking.

• observable (string) – Event you are tracking, available: ‘DCOs’: merger event of a DCO system ‘GRB1’: gamma ray bursts of star 1 ‘GRB2’: gamma ray bursts of star 2

• sensitivity (string) – This takes into account the detector sensitivity, available: ‘infinite’: p_det = 1 ‘beamed’: TODO for GRBs

Returns:

Return the DCOs merger rate density (Gpc^-3 yr^-1) as a function of cosmolgocial redshift as in Eq. (D.1) in Bavera et al. (2022) arXiv:2106.15841

Return type:

array doubles

get_centers_metallicity_bins()

Return the centers of the metallicity bins.

Returns:

Returns sampled metallicities of the populattion. This correponds to the center of each metallicity bin.

Return type:

array double

get_centers_redshift_bins()

Compute redshift bin centers.

Returns:

We devide the cosmic time history of the Universe in equally spaced bins of cosmic time of self.delta_t (100 Myr default) an compute the redshift corresponding to center of these bins.

Return type:

array doubles

get_comoving_disntance_from_redshift(z)

Compute the comoving distance from redshift.

Parameters:

z (double) – Cosmological redshift.

Returns:

Comoving distance in Mpc corresponding to the redhisft z.

Return type:

double

get_cosmic_time_at_dco_merger(z_birth)

Get cosmic time at DCO merger.

Parameters:

z_birth (double) – Cosmological redshift of formation of the DCO system (must be the same for every binary).

Returns:

Cosmic time in Gyr at DCO merger for all binaries born at z_birth.

Return type:

double

get_cosmic_time_from_redshift(z)

Compute the cosmic time from redshift.

Parameters:

z (double) – Cosmological redshift.

Returns:

Return age of the cosmic time in Gyr given the redshift z.

Return type:

double

get_data(var, index=None)

Resample class elements.

Parameters:

• var (string) – Key of self.df. This method support a list of custom definitios for DCO studies like q, m_tot, m_chirp, chi_eff.

• index (list of int) – List of indicies of the binaries of interest.

Returns:

Array containing the self.df[var][index].

Return type:

array

get_edges_metallicity_bins()

Return the edges of the metallicity bins.

Returns:

Returns the edges of all metallicity bins. We assume metallicities were binned in log-space.

Return type:

array double

get_edges_redshift_bins()

Compute redshift bin edges.

Returns:

We devide the cosmic time history of the Universe in equally spaced bins of cosmic time of self.delta_t (100 Myr default) an compute the redshift corresponding to edges of these bins.

Return type:

array doubles

get_redshift_at_dco_merger(z_birth)

Get redshift of merger of DCOs.

Parameters:

z_birth (double) – Redshift of formation of the DCO system (must be the same for every binary).

Returns:

Redshift of merger of DCOs born at z_birth.

Return type:

double

get_redshift_from_cosmic_time(t_cosm)

Compute the cosmological redshift given the cosmic time..

Parameters:

t_cosm (array doubles) – Cosmic time to which you want to know the redhisft.

Returns:

Cosmolgocial redshift corresponding to the cosmic time.

Return type:

array doubles

get_redshift_from_cosmic_time_interpolator()

Interpolator to compute the cosmological redshift given the cosmic time.

Returns:

Returns the trained interpolator object.

Return type:

object

get_shell_comovig_volume(z_hor_i, z_hor_f, sensitivity='infinite')

Compute comoving volume corresponding to a redshift shell.

Parameters:

• z_hor_i (double) – Cosmological redshift. Lower bound of the integration.

• z_hor_f (double) – Cosmological redshift. Upper bound of the integration.

• sensitivity (string) – hoose which GW detector sensitivity you want to use. At the moment only ‘infinite’ is available, i.e. p_det = 1.

Returns:

Retruns the comoving volume between the two shells z_hor_i and z_hor_f in Gpc^3.

Return type:

double

get_time_GRB(z_birth, event=None)

Get the time of the GRB.

Parameters:

• z_brith (double) – Redshif of birth.

• event (string) – Event you are tracking, either first or second core collpase: ‘CC1’, ‘CC2’.

Returns:

t_BRB – Cosmic time of the GRB event in Gyr.

Return type:

double

load_grb_rate_weights(sensitivity, path_to_dir='./', extention='npz')

Load the cosmological weights of the transient events associated to the population.

Parameters:

• sensitivity (string) – Assume there are no selection effects. Available: ‘infinite’: whole GRB population, i.e. p_det = 1

• path_to_dir (string) – Path to the directory where you the cosmological weights are stored.

Returns:

Return the cosmological weights, z_formation, z_GRB and binary index k associated to each weighted binary.

Return type:

array doubles

load_merger_rate_weights(sensitivity, path_to_dir='./', extention='npz')

Load the cosmological weights of the DCO populatio.

Parameters:

• sensitivity (string) –

  GW detector sensitivity and network configuration you want to use, see arXiv:1304.0670v3 detector sensitivities are taken from: https://dcc.ligo.org/LIGO-T2000012-v2/public available sensitivity keys (for Hanford, Livingston, Virgo network):

  ’O3actual_H1L1V1’ : aligo_O3actual_H1.txt, aligo_O3actual_L1.txt, avirgo_O3actual.txt ‘O4low_H1L1V1’ : aligo_O4low.txt, aligo_O4low.txt, avirgo_O4high_NEW.txt ‘O4high_H1L1V1’ : aligo_O4high.txt, aligo_O4high.txt, avirgo_O4high_NEW.txt ‘design_H1L1V1’ : AplusDesign.txt, AplusDesign.txt, avirgo_O5high_NEW.txt ‘infinite’: intrinsic merging DCO population, i.e. p_det = 1

• path_to_dir (string) – Path to the directory where you the cosmological weights are stored.

Returns:

Return the cosmological weights, z_formation, z_merger and binary index k associated to each weighted binary.

Return type:

array doubles

m_chirp(m_1, m_2)

mass_ratio(m_1, m_2)

merger_rate_weight(z_birth, z_merger, p_det, i)

Compute the merger rate weight (w_ijk) in yr^-1 units.

Parameters:

• z_birth (array doubles) – Cosmological redshift of formation of the binary systems. This MUST be the same for all binaries.

• z_merger (array doubles) – Cosmological redshift of merger of the binary systems.

• p_det (array doubles) – Detection probability of the binary.

• i (array integers) – Indicies correponding to the binaries you want to select out of the population.

Returns:

Return the cosmological weights w_ijk (detection rate contibution) of the binary k in the metallicity bin j born at redshift birth i as in Eq. (B.8) of Bavera et al. (2020).

Return type:

array doubles

posydon.popsyn.selection_effects

Simple utility for generating detection weights

Uses grid of detection probabilities to estimate detection probabilities

Anticipates data as Pandas dataframe with series [‘m1’, ‘q’, ‘z’, ‘chieff’]

class posydon.popsyn.selection_effects.KNNmodel(grid_path, sensitivity_key, verbose=False)

Bases: object

K-nearest neighbor model that instantiates based on detection probability grid

When instantiating, must supply path to the grid, and key that represents GW network and sensitivity.

Instantiates KNNmodel class and trains the KNN.

grid_pathstring

Path to grid of detection probabilities.

sensitivity_keystring

GW detector sensitivity and network configuration you want to use,

see arXiv:1304.0670v3

detector sensitivities are taken from: https://dcc.ligo.org/LIGO-T2000012-v2/public

available sensitivity keys (for Hanford, Livingston, Virgo network):

‘O3actual_H1L1V1’ : aligo_O3actual_H1.txt, aligo_O3actual_L1.txt, avirgo_O3actual.txt ‘O4low_H1L1V1’ : aligo_O4low.txt, aligo_O4low.txt, avirgo_O4high_NEW.txt ‘O4high_H1L1V1’ : aligo_O4high.txt, aligo_O4high.txt, avirgo_O4high_NEW.txt ‘design_H1L1V1’ : AplusDesign.txt, AplusDesign.txt, avirgo_O5high_NEW.txt

detection probabilities are calculated using the IMRPhenomXHM approximant with a network SNR threshold of 10

verboseboolean

Adds verbosity.

static normalize(x, xmin, xmax, a=0, b=1)

normalizes data on range [a,b]

predict_pdet(data, verbose=False)

Gives relative weight to each system in data based on its proximity to the points on the grid. Each system in data should have a primary mass m1, mass ratio q, redshift z, and effective spin chieff This function will determine detection probabilities using nearest neighbor algorithm in [log(m1), q, log(z), chieff] space Need to specify bounds (based on the trained grid) so that the grid and data get normalized properly

dataPandas dataframe

Data you wish to predict detection probabilities for. Required series in the dataframe:

‘m1’ : primary source-frame mass ‘q’ : mass ratio (secondary mass/primary mass) ‘z’ : redshift of merger ‘chieff’ : effective inspiral spin

verboseboolean

Adds verbosity.

posydon.popsyn.star_formation_history

Implements the selection of different star-formation history scenarios.

posydon.popsyn.star_formation_history.fractional_SFR_at_given_redshift(z, SFR_at_z, SFR, sigma, bins, binplace, Z_max, select_one_met=False)

Integrated SFR over deltaZ at a given z as in Eq. (B.9) of Bavera et al. (2020).

Parameters:

• SFR (string) – Star formation rate assumption: - Madau+Fragos17 see arXiv:1606.07887 - Madau+Dickinson14 see arXiv:1403.0007 - IllustrisTNG see see arXiv:1707.03395 - Neijssel+19 see arXiv:1906.08136

• Z (double) – Metallicity.

Returns:

The total mass of stars formed per comoving volume at a given redshift z for a given metallicity range deltaZ.

Return type:

double

posydon.popsyn.star_formation_history.get_formation_times(N_binaries, star_formation='constant', **kwargs)

Get formation times of binaries in a population based on a SFH scenario.

Parameters:

• N_binaries (int) – Number of formation ages to produce.

• star_formation (str, {constant, burst}) – Constant - random formation times from a uniform distribution. Burst - all stars are born at the same time.

• burst_time (float, 0 (years)) – Sets birth time in years.

• min_time (float, 0 (years)) – If constant SF, sets minimum of random sampling.

• max_time (float, age_of_universe (years)) – If constant SF, sets maximum of random sampling.

• RNG (<class, np.random.Generator>) – Random generator instance.

Returns:

The formation times array.

Return type:

array

posydon.popsyn.star_formation_history.get_illustrisTNG_data(verbose=False)

Load IllustrisTNG SFR dataset.

posydon.popsyn.star_formation_history.integrated_SFRH_over_redshift(SFR, sigma, Z, Z_max)

Integrated SFR history over z as in Eq. (B.10) of Bavera et al. (2020).

Parameters:

• SFR (string) – Star formation rate assumption: - Madau+Fragos17 see arXiv:1606.07887 - Madau+Dickinson14 see arXiv:1403.0007 - Neijssel+19 see arXiv:1906.08136

• Z (double) – Metallicity.

Returns:

The total mass of stars formed per comoving volume at a given metallicity Z.

Return type:

double

posydon.popsyn.star_formation_history.mean_metallicity(SFR, z)

Empiric mean metallicity function.

Parameters:

• SFR (string) – Star formation rate assumption: - Madau+Fragos17 see arXiv:1606.07887 - Madau+Dickinson14 see arXiv:1403.0007 - Neijssel+19 see arXiv:1906.08136

• z (double) – Cosmological redshift.

Returns:

Mean metallicty of the universe at the given redhist.

Return type:

double

posydon.popsyn.star_formation_history.star_formation_rate(SFR, z)

Star formation rate in M_sun yr^-1 Mpc^-3.

Parameters:

• SFR (string) – Star formation rate assumption: - Madau+Fragos17 see arXiv:1606.07887 - Madau+Dickinson14 see arXiv:1403.0007 - Neijssel+19 see arXiv:1906.08136 - IllustrisTNG see see arXiv:1707.03395

• z (double) – Cosmological redshift.

Returns:

The total mass of stars in M_sun formed per comoving volume Mpc^-3 per year.

Return type:

double

posydon.popsyn.star_formation_history.std_log_metallicity_dist(sigma)

Standard deviation of the log-metallicity distribution.

Returns:

Standard deviation of the adopted distribution.

Return type:

double

posydon.popsyn.synthetic_population

Evolve multiple BinaryPopulations together.

e.g. with multiple metallicities

class posydon.popsyn.synthetic_population.SyntheticPopulation(path_to_ini, verbose=False, MODEL={})

Bases: object

Parameters:

path (str) – Path to the inifile to parse. You can supply a list in the metallicity parameter to evolve more than one population.

apply_logic(df, S1_state=None, S2_state=None, binary_state=None, binary_event=None, step_name=None, invert_S1S2=False, warn=True)

Select binaries in a dataframe given some properties.

Parameters:

• df (pd.DataFrame) – POSYDON binary population synthesis dataframe.

• S1_state (str) – Star1 stellar state.

• S2_state (str) – Star2 stellar state.

• binary_state (str) – Binary state.

• binary_event (str) – Binary event.

• step_name (str) – Name of posydon step.

• invert_S1S2 (bool) – If True isolated also sort S1_state=S2_state and S2_state=S1_state systems.

Returns:

List of binaries to select given the search parameters.

Return type:

pd.DataFrame of bools

compute_cosmological_weights(sensitivity, flag_pdet, working_dir, load_data, pop='DCO')

Compute the GRB/DCO merger rate weights.

Parameters:

• sensitivity (str) –

  GW detector sensitivity and network configuration you want to use, see arXiv:1304.0670v3 detector sensitivities are taken from: https://dcc.ligo.org/LIGO-T2000012-v2/public available sensitivity keys (for Hanford, Livingston, Virgo network):

  ’O3actual_H1L1V1’ : aligo_O3actual_H1.txt, aligo_O3actual_L1.txt, avirgo_O3actual.txt ‘O4low_H1L1V1’ : aligo_O4low.txt, aligo_O4low.txt, avirgo_O4high_NEW.txt ‘O4high_H1L1V1’ : aligo_O4high.txt, aligo_O4high.txt, avirgo_O4high_NEW.txt ‘design_H1L1V1’ : AplusDesign.txt, AplusDesign.txt, avirgo_O5high_NEW.txt ‘infinite’: intrinsic merging DCO population, i.e. p_det = 1

• flag_pdet (bool) – True if you use sensitivity != ‘infinite’.

• working_dir (str) – Working directory where the weights will be saved.

• load_data (bool) – True if you want to load the weights computed by this function in your working directory.

• **kwargs (dict) – Kwargs containing the model parameters of your rate calculation. See posydon/popsyn/rate_calculation.py

Returns:

Return the cosmological weights, z_formation, z_merger and binary index k associated to each weighted binary.

Return type:

array doubles

create_binary_populations()

Create a list of BinaryPopulation objects.

static create_met_prefix(met)

Append a prefix to the name of directories for batch saving.

evolve()

Evolve population(s) at given Z(s).

get_dco_at_formation(S1_state, S2_state, oneline_cols=None, formation_channels=False, mt_history=False)

Populates df_synthetic with DCOs at their formation.

If formation_channels is True the channel column is added to the df_synthetic dataframe.

if MODEL on class initialization is not None and “compute_GRB_properties” in MODEL. If MODEL[“compute_GRB_properties”] is True the following columns are in the MODEL:

• ‘GRB_efficiency’,

• ‘GRB_beaming’,

• ‘E_GRB_iso_min’

The following columns are added to the df_synthetic dataframe:

• S1_m_disk_radiated

• S2_m_disk_radiated

Note: by default this function looks for the symmetric state S1_state = S2_sate and S2_state = S1_sate.

Parameters:

• S1_state (str) – Star1 stellar state.

• S2_state (str) – Star2 stellar state.

• oneline_cols (list str) – List of columns preset in the oneline dataframe you want to export into the synthetic population.

• formation_channels (bool) – Compute the formation channel, a string containing the binary event evolution.

• mt_history (bool) – If True, split the event oRLO1/oRLO2 into oRLO1-contact/oRLO2-contact, oRLO1-reverse/oRLO2-reverse and oRLO1/oRLO2. This is useful to identify binaries undergoing contact stable mass-transfer phases and reverse mass-transfer phase .

get_dco_detection_rate(sensitivity='design_H1L1V1', export_cols=None, working_dir='./', load_data=False)

Compute the detection rate per yr.

Parameters:

• sensitivity (str) –

  GW detector sensitivity and network configuration you want to use, see arXiv:1304.0670v3 detector sensitivities are taken from: https://dcc.ligo.org/LIGO-T2000012-v2/public available sensitivity keys (for Hanford, Livingston, Virgo network):

  ’O3actual_H1L1V1’ : aligo_O3actual_H1.txt, aligo_O3actual_L1.txt, avirgo_O3actual.txt ‘O4low_H1L1V1’ : aligo_O4low.txt, aligo_O4low.txt, avirgo_O4high_NEW.txt ‘O4high_H1L1V1’ : aligo_O4high.txt, aligo_O4high.txt, avirgo_O4high_NEW.txt ‘design_H1L1V1’ : AplusDesign.txt, AplusDesign.txt, avirgo_O5high_NEW.txt

• export_cols (list str) – List of additional columns to save in the intrinsic/observable population.

• working_dir (str) – Working directory where the weights will be saved.

• load_data (bool) – True if you want to load the weights computed by this function in your working directory.

get_dco_merger_efficiency()

Compute the DCO merger efficinty per Msun for each metallicities.

get_dco_merger_rate_density(export_cols=None, working_dir='./', load_data=False)

Compute the merger rate density as a function of redshift.

Parameters:

• export_cols (list str) – List of additional columns to save in the intrinsic/observable population.

• working_dir (str) – Working directory where the weights will be saved.

• load_data (bool) – True if you want to load the weights computed by this function in your working directory.

get_formation_channels(mt_history)

Get formation channel and add to df and df_oneline.

get_grb_rate_density(export_cols=None, working_dir='./', load_data=False)

Compute the GRB density as a function of redshift.

Parameters:

• export_cols (list str) – List of additional columns to save in the intrinsic/observable population.

• working_dir (str) – Working directory where the weights will be saved.

• load_data (bool) – True if you want to load the weights computed by this function in your working directory.

get_ini_kw()

load_intrinsic_pop(path, pop='DCO')

Load intrinsic population.

Parameters:

path (str) – Path to dataset.

load_observable_pop(path, pop='DCO')

Load observable population.

Parameters:

path (str) – Path to dataset.

load_pop(path)

Load parsed population.

Parameters:

path (str) – Path to dataset.

load_synthetic_pop(path)

Load synthetc population.

Parameters:

path (str) – Path to dataset.

merge_parallel_runs(path_to_batches)

Merge the folder or list of folders into a single file per metallicity.

Parameters:

path_to_batches (str or list of str) – Path to the folder(s) containing the batch folders.

parse(path_to_data, S1_state=None, S2_state=None, binary_state=None, binary_event=None, step_name=None, invert_S1S2=False, chunksize=500000)

Sort binaries of interests given some properties.

It also stores the underlying stellar mass and the initial simulated stellar mass for each metallicity.

Parameters:

• S1_state (str) – Star1 stellar state.

• S2_state (str) – Star2 stellar state.

• binary_state (str) – Binary state.

• binary_event (str) – Binary event.

• step_name (str) – Name of posydon step.

• invert_S1S2 (bool) – If True isolated also sort S1_state=S2_state and S2_state=S1_state systems.

• chunksize (int) – Read the POSYDON binary population in chuncks to prevent OFM error.

plot_hist_properties(var, intrinsic=False, observable=False, pop=None, **kwargs)

Plot histogram of intrinsic/observable properites.

Parameters:

• var (str) – Property to plot stored in intrinsic/observable dataframe.

• intrinsic (bool) – True if you want to deplay the intrisc population.

• observable (bool) – True if you want to deplay the observable population.

• **kwargs (dict) – ploting arguments

plot_merger_efficiency(**kwargs)

Plot merger rate efficinty.

plot_popsyn_over_grid_slice(grid_type, met_Zsun, **kwargs)

Plot popsyn over grid slice.

plot_rate_density(DCO=False, GRB=False, **kwargs)

Plot DCO and GRB rate densities.

resample_synthetic_population(index, z_formation, z_event, w_ijk, export_cols=None, pop='DCO', reset_grb_properties=None)

Resample synthetc population to obtain intrinsic/observable population.

Parameters:

• index (array int) – Index k of each binary corresponding to the synthetc dataframe proeprties.

• z_formation (array float) – Redshift of formation of each binary.

• z_merger (array float) – Redshift of merger of each binary.

• w_ijk (array float) – Cosmological weights computed with Eq. B.8 of Bavera et at. (2020).

• export_cols (list str) – List of additional columns to save in the intrinsic/observable population.

Returns:

Resampled synthetc population to intrinsic or detecatable population.

Return type:

pd.DataFrame

save_intrinsic_pop(path='./intrinsic_population_type.h5', pop='DCO')

Save intrinsic population.

Parameters:

path (str) – Path to dataset.

save_observable_pop(path='./observable_population_type.h5', pop='DCO')

Save observable population.

Parameters:

path (str) – Path to dataset.

save_pop(path='./parsed_population.h5')

Save parsed population.

Parameters:

path (str) – Path to file where you want to export the dataset.

save_synthetic_pop(path='./synthetic_population.h5')

Save synthetc population.

Parameters:

path (str) – Path to dataset.