Common functions to be used while running populations.
- posydon.utils.common_functions.BSE_to_POSYDON(ktype)[source]
Convert BSE numerical type to POSYDON string.
- posydon.utils.common_functions.CEE_parameters_from_core_abundance_thresholds(star, verbose=False)[source]
Find the envelope mass for different core boundary abundance thresholds.
The results are meant to be used in collabration with the respective lambda_CE_*cent, lambda_CE_pure_He_star_10cent.
- Parameters
star (SingleStar object holding the history of its attributes.) –
- Returns
None
It updates the following values in the star object
co_core_mass_at_He_depletion (float) – co_core_mass at He core depletion (almost at the same time as carbon core ignition).
avg_c_in_c_core_at_He_depletion (float) – avg carbon abundance inside CO_core_mass at He core depletion (almost at the same time as carbon core ignition).
- posydon.utils.common_functions.CO_radius(M, COtype)[source]
Calculate the radius of a compact object based on its type and mass.
- posydon.utils.common_functions.He_MS_lifetime(mass)[source]
Calculate the lifetime of He burning in a star.
- posydon.utils.common_functions.POSYDON_to_BSE(star)[source]
Convert POSYDON state to BSE numerical type.
- Parameters
star (SingleStar) – The star which state requires conversion.
- Returns
The corresponding BSE numerical type.
- Return type
- class posydon.utils.common_functions.PchipInterpolator2(*args, positive=False, **kwargs)[source]
Bases:
objectInterpolation class.
Initialize the interpolator.
- posydon.utils.common_functions.Schwarzschild_Radius(M)[source]
Calculate the Schwarzschild Radius of BH with mass M.
- posydon.utils.common_functions.beaming(binary)[source]
Calculate the geometrical beaming of a super-Eddington accreting source.
Compute the super-Eddington isotropic-equivalent accretion rate and the beaming factor of a star. This does not change the intrinsic accretion onto the accretor and is an observational effect due to the inflated structure of the accretion disc that beams the outgoing X-ray emission. This is important for observing super-Eddington X-ray sources (e.g. ultraluminous X-ray sources). In case of a BH we are assuming that it has zero spin which is not a good approximation for high accretion rates.
- Parameters
binary (BinaryStar) – The binary object.
- Returns
The super-Eddington isotropic-equivalent accretion rate and beaming factor respcetively in solar units.
- Return type
References
- 1
Shakura, N. I. & Sunyaev, R. A. 1973, A&A, 24, 337
- 2
King A. R., 2008, MNRAS, 385, L113
- posydon.utils.common_functions.bondi_hoyle(binary, accretor, donor, idx=- 1, wind_disk_criteria=True, scheme='Hurley+2012')[source]
Calculate the Bondi-Hoyle accretion rate of a binary.
- Parameters
binary (BinaryStar) – The binary which accretion rate is required.
accretor (SingleStar) – The accretor in the binary.
donor (SingleStar) – The donor in the binary.
- Returns
The Bondi-Hoyle accretion rate in solar units.
- Return type
Notes
A approximation is used for the accretion rate[2_] and the wind velocity of the donor is moddeled as in [3].
References
- 1
Bondi, H., & Hoyle, F. 1944, MNRAS, 104, 273
- 2
Boffin, H. M. J., & Jorissen, A. 1988, A&A, 205, 155
- 3
Hurley, J. R., Tout, C. A., & Pols, O. R. 2002, MNRAS, 329, 897
- 4
Belczynski, K., Kalogera, V., Rasio, F. A., et al. 2008, ApJS, 174, 223
- 5
Sen, K. ,Xu, X. -T., Langer, N., El Mellah, I. , Schurmann, C., & Quast, M., 2021, A&A
- 6
Sander A. A. C., Vink J. S., 2020, MNRAS, 499, 873
- 7
Kudritzki, R.-P., & Puls, J. 2000, ARA&A, 38, 613
- posydon.utils.common_functions.calculate_H2recombination_energy(profile, tolerance=0.001)[source]
Compute the recombination energy of H2 per shell in erg.
- Parameters
profile (array) – Donor’s star profile from MESA
tolerance (float) – The tolerance of numerical difference in two floats when comparing and testing results.
- Returns
specific_donor_H2recomb_energy – recombination energy of H2 per shell in ergs
- Return type
array
- posydon.utils.common_functions.calculate_Patton20_values_at_He_depl(star)[source]
Calculate the carbon core mass and abundance very close to ignition.
This is important for using the Patton+2020 SN prescription
- Parameters
star (SingleStar object holding the history of its attributes.) –
- Returns
None
It updates the following values in the star object
co_core_mass_at_He_depletion (float) – co_core_mass at He core depletion (almost at the same time as carbon core ignition)
avg_c_in_c_core_at_He_depletion (float) – avg carbon abundance inside CO_core_mass at He core depletion (almost at the same time as carbon core ignition)
- posydon.utils.common_functions.calculate_binding_energy(donor_mass, donor_radius, donor_dm, specific_internal_energy, ind_core, factor_internal_energy, verbose, tolerance=0.001)[source]
Calculate the total binding energy of the envelope of the star.
- Parameters
donor_mass (array) – Enclosed mass coordinate of the donor star from its profile.
donor_radius (array) – Radius coordinate of the donor star from its profile.
donor_dm (array) – Mass enclosed per shell in the donor star’s profile.
specific_internal_energy (array) – Specific internal energy of the donor star.
ind_core (int) – The value of the shell position of the core - envelope boundary, at the donor’s MESA profile
factor_internal_energy (float) – The factor to multiply with internal energy to be taken into account when we calculate the binding energy of the enevelope
verbose (bool) – In case we want information about the CEE (the default is False).
- Returns
Ebind_i – The total binding energy of the envelope of the star
- Return type
- posydon.utils.common_functions.calculate_core_boundary(donor_mass, donor_star_state, profile, mc1_i=None, core_element_fraction_definition=None, CO_core_in_Hrich_star=False)[source]
Calculate the shell where the core is - envelope boundary.
- Parameters
donor_mass (array) – Profile column of enclosed mass of the star.
donor_star_state (string) – The POSYDON evolutionary state of the donor star
profile (numpy.array) – Donor’s star profile from MESA
mc1_i (float) – core mass and total mass of the donor star.
core_element_fraction_definition (float) – The mass fraction of the envelope abundant chemical element at the core-envelope boundary to derive the donor’s core mass from the profile
CO_core_in_Hrich_star (Bool) – This should be true if we want to calculate the boundary of CO core in a H-rich star (and not of the helium core).
- Returns
ind_core – The value of the cell position of the core - envelope boundary, at the donor’s MESA profile (for a profile that starts from the surface). More specifically, it returns the index of the first cell (starting from the surface), that the elements conditions for the core are met. - Returns 0 for a star that is all core - Returns -1 for a star that is all envelope.
- Return type
- posydon.utils.common_functions.calculate_lambda_from_profile(profile, donor_star_state, m1_i=nan, radius1=nan, common_envelope_option_for_lambda='lambda_from_profile_gravitational_plus_internal_minus_recombination', core_element_fraction_definition=0.1, ind_core=None, common_envelope_alpha_thermal=1.0, tolerance=0.001, CO_core_in_Hrich_star=False, verbose=False)[source]
Calculate common-enevelope lambda from the profile of a star.
We also pass a more accurate calculation of the donor core mass for the purposes of common-envelope evolution.
- Parameters
profile (numpy.array) – Donor’s star profile from MESA
donor_star_state (string) – The POSYDON evolutionary state of the donor star !!!!
common_envelope_option_for_lambda (str) –
Available options: * ‘default_lambda’: using for lambda the constant value of common_envelope_lambda_default parameter * ‘lambda_from_profile_gravitational’: calculating the lambda parameter from the donor’s profile by using the gravitational binding energy from the surface to the core (needing “mass”, and “radius” as columns in the profile) * ‘lambda_from_profile_gravitational_plus_internal’: as above
but taking into account a factor of common_envelope_alpha_thermal * internal energy too in the binding energy (needing also “energy” as column in the profile)
’lambda_from_profile_gravitational_plus_internal_minus_recombination’
as above but not taking into account the recombination energy in the internal energy (needing also “y_mass_fraction_He”, “x_mass_fraction_H” “neutral_fraction_H”, “neutral_fraction_He”, and “avg_charge_He” as column in the profile)
core_element_fraction_definition (float) – The mass fraction of the envelope abundant chemical element at the core-envelope boundary to derive the donor’s core mass from the profile.
ind_core (int) – The value of the cell position of the core - envelope boundary, at the donor’s MESA profile (for a profile that starts from the surface). More specifically, it returns the index of the first cell (starting from the surface), that the elements conditions for the core are met. It is 0 for a star that is all core and -1 for a star that is all envelope. If it is not given (None), it will be calculated inside the function.
common_envelope_alpha_thermal (float) – Used and explained depending on the common_envelope_option_for_lambda option above.
tolerance (float) – The tolerance of numerical difference in two floats when comparing and testing results.
CO_core_in_Hrich_star (Bool) – This should be true if we want to calculate the boundary of CO core in a H-rich star (and not of the helium core).
verbose (bool) – In case we want information about the CEE.
- Returns
lambda_CE (float) – lambda_CE for the envelope of the donor in CEE, calculated from profile
mc1_i (float) – More accurate calculation of the donor core mass for the purposes of CEE.
rc1_i (float) – More accurate calculation of the donor core radius for the purposes of CEE.
- posydon.utils.common_functions.calculate_recombination_energy(profile, tolerance=0.001)[source]
Compute the recombination energy per shell in erg.
- Parameters
profile (numpy.array) – Donor’s star profile from MESA
tolerance (float) – The tolerance of numerical difference in two floats when comparing and testing results.
- Returns
specific_donor_recomb_energy – recombination energy per shell in ergs
- Return type
array
- posydon.utils.common_functions.check_state_of_star(star, i=None, star_CO=False)[source]
Get the state of a SingleStar.
- Parameters
star (SingleStar) – The star for which the state will be computed.
i (integer) – Index of the model for which we want to calculate the state of the SingleStar object. Default = -1 (the final).
star_CO (bool) – True if we want to assume a compact object (WD/NS/BH). False if the state will be calculated by its attributes.
- Returns
state – state at of the star object at index i of the history.
- Return type
- posydon.utils.common_functions.check_state_of_star_history_array(star, N=1, star_CO=False)[source]
Calculate the evolutionary states with an array of history data.
- Parameters
star (SingleStar) – The star for which the state will be computed.
N (int) – Number of history steps (from the end), to calculate the state.
star_CO (bool) – If True, assume it’s a compact object.
- Returns
The state(s) in a list.
- Return type
list of str
- posydon.utils.common_functions.cumulative_mass_transfer_flag(MT_cases)[source]
Get the cumulative MT string from a list of integer MT casses.
- posydon.utils.common_functions.cumulative_mass_transfer_numeric(MT_cases)[source]
Summarize the history of MT cases in a short list of integers.
- Parameters
MT_cases (array-like) – A list of the integer MT flags at sequential history steps.
- Returns
list of int – A shorter list of integer MT flags, following these rules: i. If undetermined MT at any step, it is indicated in the beginning
(as a warning) and ignored later.
If no RLO anywhere, then this is the only element in the returned list (or the second if undetermined MT at any step). Intermediate no-RLO phases (between RLO cases) are ignored.
Consequent same cases are reported only once (e.g., A, A, A -> A.)
The end result is a list of integers indicating whether undetermined MT
anywhere, if no RLO everywhere, or “changes” of MT cases.
- posydon.utils.common_functions.cumulative_mass_transfer_string(cumulative_integers)[source]
Convert a cumulative MT sequence to a string.
- Parameters
cumulative_integers (list of int) – Typically, the output of cumulative_mass_transfer_numeric.
- Returns
A summarization of the mass-tranfer cases in the form of a string, as opposed to the output of cumulative_mass_transfer_numeric (see this function to understand the rules of summarization). The character ? in the beginning of the string indicates undetermined MT case at some point of the evolution. no_RLO indicates no RLO at any evolutionary step. caseA, caseB, etc., denote the corresponding MT cases. When multiple cases are found, they are indicated only when the begin, and are combined using /. For example:
?no_RLO : undetermined MT at few steps, otherwise no RLO. caseA : case A MT only (possible no_RLO at some points). ?caseA/B : undetermined MT somewhere, then case A, then case B. caseA/B/A : case A, then B, and A again (although unphysical).
- Return type
- posydon.utils.common_functions.eddington_limit(binary, idx=- 1)[source]
Calculate the Eddington limit & radtiative efficiency of compact object.
- Parameters
binary (BinaryStar) – The binary object.
- Returns
The Eddington accretion limit and radiative efficiency in solar units.
- Return type
- posydon.utils.common_functions.get_binary_state_and_event_and_mt_case(binary, interpolation_class=None, i=None, verbose=False)[source]
Infer the binary state, event and mass transfer case.
- Parameters
binary (BinaryStar) – The POSYDON binary star.
i (int) – The index of the history in which we want to calculate the state of the binary object. Default (None) is the current state.
- Returns
binary_state (str) – One of ‘detached’, ‘contact’, ‘RLO1’ and ‘RLO2’.
binary_event (str) – Options are ‘oRLO1’ or ‘oRLO2’ (onset of RLO, the start of RLO), ‘oCE1’, ‘oCE2’, ‘oDoubleCE1’, ‘oDoubleCE2’, ‘CC1’, ‘CC2’.
mass transfer case (str) – ‘caseA’, ‘caseB’, etc.
Examples
If ‘detached’ then returns [‘detached’, None, None].
If ‘contact’ then returns [‘contact’, None] or [‘oCE1’, ‘oDoubleCE1’] or [‘oDoubleCE2’, None].
If RLO then returns either [‘RLO1’, None, ‘caseXX’] or [‘RLO2’, None, ‘caseXX’] or maybe [‘RLO2’, ‘oRLO2’, ‘caseXX’].
- posydon.utils.common_functions.get_binary_state_and_event_and_mt_case_array(binary, N=None, verbose=False)[source]
Calculate the evolutionary states with an array of history data.
- Parameters
binary (POSYDON BinaryStar object) –
N (array) – index of the history in which we want to calculate the state of the SingleStar object
- Returns
binary_state (str(see in check_state_of_star))
binary_event
MT_case
- posydon.utils.common_functions.get_internal_energy_from_profile(common_envelope_option_for_lambda, profile, tolerance=0.001)[source]
Calculate the specific internal energy per shell of the donor.
- Parameters
common_envelope_option_for_lambda (str) –
Available options: * ‘default_lambda’: using for lambda the constant value of common_envelope_lambda_default parameter * ‘lambda_from_profile_gravitational’: calculating the lambda parameter from the donor’s profile by using the gravitational binding energy from the surface to the core (needing “mass”, and “radius” as columns in the profile) * ‘lambda_from_profile_gravitational_plus_internal’: as above
but taking into account a factor of common_envelope_alpha_thermal * internal energy too in the binding energy (needing also “energy” as column in the profile)
’lambda_from_profile_gravitational_plus_internal_minus_recombination’
as above but not taking into account the recombination energy in the internal energy (needing also “y_mass_fraction_He”, “x_mass_fraction_H” “neutral_fraction_H”, “neutral_fraction_He”, and “avg_charge_He” as column in the profile)
profile (numpy.array) – Donor’s star profile from MESA
tolerance (float) – The tolerance of numerical difference in two floats when comparing and testing results.
- Returns
specific_donor_internal_energy – Value of the specific internal energy per shell of the donor
- Return type
array
- posydon.utils.common_functions.get_mass_radius_dm_from_profile(profile, m1_i=0.0, radius1=0.0, tolerance=0.001)[source]
TODO: add summary.
Reads and returns the profile columms of enclosed mass radius and mass per shell of the donor star from a MESA profile.
- Parameters
m1_i (float) – m1_i is the value passed from the singlestar object, for testing purposes only
radius1 (float) – radius1 is the value passed from the singlestar object, for testing purposes only
profile (numpy.array) – Donor’s star profile from MESA
tolerance (float) – The tolerance of numerical difference in two floats when comparing and testing results.
- Returns
donor_mass (array) – Profile column of enclosed mass of the star.
donor_radius (array) – Profile column of the radius the star.
donor_dm (array) – Profile mass per shell of the star.
- posydon.utils.common_functions.histogram_sampler(x_edges, y, size=1)[source]
Sample from an empirical PDF represented by a histogram.
- Parameters
x_edges (array-like) – The edges of the bins of the histrogram.
y (array-like) – The counts (or a scaled version of them) of the histogram.
size (int) – Number of random values to produce.
- Returns
The random sample.
- Return type
array
- posydon.utils.common_functions.infer_mass_transfer_case(rl_relative_overflow, lg_mtransfer_rate, donor_state, verbose=False)[source]
Infer the mass-transfer case of a given star.
- posydon.utils.common_functions.infer_star_state(star_mass=None, surface_h1=None, center_h1=None, center_he4=None, center_c12=None, log_LH=None, log_LHe=None, log_Lnuc=None, star_CO=False)[source]
Infer the star state (corresponding to termination flags 2 and 3).
- posydon.utils.common_functions.initialize_empty_array(arr)[source]
Initialize an empty record array with NaNs and empty strings.
- posydon.utils.common_functions.inspiral_timescale_from_orbital_period(star1_mass, star2_mass, orbital_period, eccentricity)[source]
Compute the timescale of GW inspiral using the orbital period.
- Based on Peters 1964:
https://journals.aps.org/pr/abstract/10.1103/PhysRev.136.B1224
- Parameters
- Returns
The inspiral time scale of the two black holes in Myr.
- Return type
References
- 1
Peters 1964 Phys. Rev. 136, B1224
- posydon.utils.common_functions.inspiral_timescale_from_separation(star1_mass, star2_mass, separation, eccentricity)[source]
Compute the timescale of GW inspiral using the orbital separation.
- Based on Peters 1964:
https://journals.aps.org/pr/abstract/10.1103/PhysRev.136.B1224
- Parameters
- Returns
The inspiral time scale of the two black holes.
- Return type
References
- 1
Peters 1964 Phys. Rev. 136, B1224
- posydon.utils.common_functions.inverse_sampler(x, y, size=1)[source]
Sample from a PDF using the inverse-sampling method.
- Parameters
x (array-like) – The x-axis coordinates of the points where the PDF is defined.
y (array-like) – The probablity density at x (or a scaled version of it).
size (int) – Number of samples to generate.
- Returns
The sample drawn from the PDF.
- Return type
array
- posydon.utils.common_functions.is_number(s)[source]
Check if the input can be converted to a float.
- posydon.utils.common_functions.linear_interpolation_between_two_cells(array_y, array_x, x_target, top=None, bot=None, verbose=False)[source]
Interpolate quantities between two star profile shells.
- posydon.utils.common_functions.orbital_period_from_separation(separation, m1, m2)[source]
Apply the Third Kepler law.
- posydon.utils.common_functions.orbital_separation_from_period(period_days, m1_solar, m2_solar)[source]
Apply the Third Kepler law.
- posydon.utils.common_functions.period_change_stabe_MT(period_i, Mdon_i, Mdon_f, Macc_i, alpha=0.0, beta=0.0)[source]
Change the binary period after a semi-detahed stable MT phase.
Calculated in Sorensen, Fragos et al. 2017A&A…597A..12S. Note that MT efficiencies are assumed constant (i.e., not time-dependent) throughout the MT phase.
- Parameters
period_i (float) – Initial period
Mdon_i (float) – Initial donor mass
Mdon_f (float) – Final donor mass (should be in the same unit’s of Mdon_i)
Mdon_i – Initial accretor’s mass (should be in the same unit’s of Mdon_i)
alpha (float [0-1]) – Fraction of DM_don (= Mdon_i - Mdon_f) from the donor, lost from the donor’s vicinity
beta (float [0-1]) – Fraction of Mdot from the L1 point (= (1-alpha)*DM_don), lost from the accretor’s vicinity. The final accreted rate is (1-beta)(1-alpha)*DM_don
- Returns
period_f – final period at the end of stable MT, in the same units as period_i
- Return type
- posydon.utils.common_functions.period_evol_wind_loss(M_current, M_init, Mcomp, P_init)[source]
Calculate analytically the period widening due to wind mass loss.
- Parameters
- Returns
Current binary period in days
- Return type
References
- 1
Tauris, T. M., & van den Heuvel, E. 2006, Compact stellar X-ray sources, 1, 623
- posydon.utils.common_functions.profile_recomb_energy(x_mass_fraction_H, y_mass_fraction_He, frac_HII, frac_HeII, frac_HeIII)[source]
Calculate the recombination energy per shell.
- Parameters
x_mass_fraction_H (array) – Mass fraction of H per shell
y_mass_fraction_He (array) – Mass fraction of He per shell.
frac_HII (array) – Fraction of single ionized H per shell.
frac_HeII (array) – Fraction of single ionized He per shell.
frac_HeIII (array) – Fraction of double ionized He per shell.
- Returns
recomb_energy – recombination energy per shell in ergs (same dimension as x_mass_fraction_H and y_mass_fraction_He)
- Return type
1D numpy.arrays
- posydon.utils.common_functions.read_histogram_from_file(path)[source]
Read a histogram from a CSV file.
The expected format is:
# comment line x[0], x[1], …, x[n], x[n+1] y[0], y[1], …, y[n]
where # denotes a comment line (also empty lines are ignored), and n is the number of bins (notice that the first line contains n+1 elements.)
Usage: bin_edges, bin_counts = read_histogram_from_file(“a_histogram.csv”).
- Parameters
path (str) – The path of the CSV file containing the histogram information.
- Returns
The bin edges and bin counts of the histogram.
- Return type
list of arrays
- posydon.utils.common_functions.rejection_sampler(x=None, y=None, size=1, x_lim=None, pdf=None)[source]
Generate a sample from a 1d PDF using the acceptance-rejection method.
- Parameters
x (array_like) – The x-values of the PDF.
y (array_like) – The y-values of the PDF.
size (int) – The number of random numbers to generate.
x_lim (array float) – The boundary where the pdf function is defined if passed as pdf.
pdf (func) – The pdf function
- Returns
An array with size random numbers generated from the PDF.
- Return type
ndarray
- posydon.utils.common_functions.roche_lobe_radius(q, a_orb=1)[source]
Approximate the Roche lobe radius from Eggleton (1983).
- Parameters
- Returns
Roche lobe radius in similar units as a_orb
- Return type
References
- 1
Eggleton, P. P. 1983, ApJ, 268, 368
- posydon.utils.common_functions.rzams(m, z=0.02, Zsun=0.02)[source]
Evaluate the zero age main sequence radius.
- Parameters
m (array_like) – The masses of the stars in Msun.
z (float) – The metallicity of the star.
- Returns
Array of same size as m containing the ZAMS radii of the stars (Rsun)
- Return type
ndarray
References
- 1
Tout C. A., Pols O. R., Eggleton P. P., Han Z., 1996, MNRAS, 281, 257
- posydon.utils.common_functions.separation_evol_wind_loss(M_current, M_init, Mcomp, A_init)[source]
Calculate analytically the separation widening due to wind mass loss.
- Parameters
- Returns
Current binary separation in Rsun
- Return type
References
- 1
Tauris, T. M., & van den Heuvel, E. 2006, Compact stellar X-ray sources, 1, 623.