posydon.binary_evol.DT

posydon.binary_evol.DT.double_CO

Detached evolution for double compact-object binaries.

class posydon.binary_evol.DT.double_CO.DoubleCO(n_o_steps_interval=None)

Bases: object

The double compact-object step class.

Initialize a DoubleCO instance.

posydon.binary_evol.DT.double_CO.event(terminal, direction=0)

Return a helper function to set attributes for solve_ivp events.

posydon.binary_evol.DT.double_CO.gr(t, y, M_acc, M)

TODO: add description and reference for the equations.

posydon.binary_evol.DT.step_detached

Detached evolution step.

posydon.binary_evol.DT.step_detached.STAR_STATES_H_RICH = ['H-rich_Core_H_burning', 'H-rich_Core_He_burning', 'H-rich_Shell_H_burning', 'H-rich_Central_He_depleted', 'H-rich_Shell_He_burning', 'H-rich_Core_C_burning', 'H-rich_Central_C_depletion', 'H-rich_non_burning', 'accreted_He_Core_H_burning', 'accreted_He_non_burning']

STAR_STATES_CO = [‘BH’, ‘NS’, ‘WD’, ]

class posydon.binary_evol.DT.step_detached.detached_step(grid_name_Hrich=None, grid_name_strippedHe=None, metallicity=None, path=PATH_TO_POSYDON_DATA, dt=None, n_o_steps_history=None, matching_method='minimize', initial_mass=None, rootm=None, verbose=False, do_wind_loss=True, do_tides=True, do_gravitational_radiation=True, do_magnetic_braking=True, magnetic_braking_mode='RVJ83', do_stellar_evolution_and_spin_from_winds=True, RLO_orbit_at_orbit_with_same_am=False, list_for_matching_HMS=None, list_for_matching_postMS=None, list_for_matching_HeStar=None)

Bases: object

Evolve a detached binary.

The binary will be evolved until Roche-lobe overflow, core-collapse or maximum simulation time, using the standard equations that govern the orbital evolution.

Parameters:

• path (str) – Path to the directory that contains a HDF5 grid.

• dt (float) – The timestep size, in years, to be appended to the history of the binary. None means only the final step. Note: do not select very small timesteps cause it may mess with the solving of the ODE.

• n_o_steps_history (int) – Alternatively, we can define the number of timesteps to be appended to the history of the binary. None means only the final step. If both dt and n_o_steps_history are different than None, dt has priority.

• matching_method (str) – Method to find the best match between a star from a previous step and a point in a single MIST-like stellar track. Options “root” (which tries to find a root of two matching quantities, and it is possible to not achieve it) or “minimize” (minimizes the sum of squares of differences of various quantities between the previous step and the track).

• verbose (Boolean) – True if we want to print stuff.

• do_wind_loss (Boolean) – If True, take into account change of separation due to mass loss from the star.

• do_tides (Booleans) – If True, take into account change of separation, eccentricity and star spin due to tidal forces.

• do_gravitational_radiation (Boolean) – If True, take into account change of separation and eccentricity due to gravitational wave radiation.

• do_magnetic_braking (Boolean) – If True, take into account change of star spin due to magnetic braking.

• magnetic_braking_mode (String) –

  A string corresponding to the desired magnetic braking prescription.

  – RVJ83: Rappaport, Verbunt, & Joss 1983 – M15: Matt et al. 2015 – G18: Garraffo et al. 2018 – CARB: Van & Ivanova 2019

• do_stellar_evolution_and_spin_from_winds (Boolean) – If True, take into account change of star spin due to change of its moment of inertia during its evolution and due to spin angular momentum loss due to winds.

KEYS

Contains valid keywords which is used to extract quantities from the grid.

Type:

list of str

grid

Object to interpolate between the time-series in the h5 grid.

Type:

GRIDInterpolator

initial_mass

Contains the initial masses of the stars in the grid.

Type:

list of float

Note

A matching between the properties of the star, and the h5 tracks are required. In the “root” solver matching_method, if the root solver fails then the evolution will immediately end, and the binary state will be tagged with “Root solver failed”. In the “minimize” matching_method, we minimize the sum of squares of differences of various quantities between the previous step and the h5 track.

Warns:

UserWarning – If the call cannot determine the primary or secondary in the binary.

Raises:

Exception – If the ode-solver fails to solve the differential equation that governs the orbital evolution.

Initialize the step. See class documentation for details.

get_root0(keys, x, htrack, rs=None)

Get the track in the grid with values closest to the requested ones.

Parameters:

• keys (list of str) – Contains the keys of the required specific quantities that will be matched in the MIST-like track.

• x (list of floats, of same length as "keys") – Contains the latest values (from a previous POSYDON step) of the quantities of “keys” in the POSYDON SingleStar object.

• rs (list of floats, same length as "keys") – Contains normalization factors to be divided for rescaling x values.

Returns:

Contains the associated initial mass (in solar units) and the time (in years) such that the time-series of the keys at that time has the closest values to x. These will become m0, t0 for the later integration during the detached binary evolution. If there is no match then NaNs will be returned instead.

Return type:

list of 2 float values

get_track_val(key, htrack, m0, t)

Return a single value from the interpolated time-series.

Parameters:

• key (str) – Keyword of the required quantity.

• m0 (float) – The associated initial mass of the required quantity.

• t (float) – The required time in the time-series.

Returns:

The value of the quantity key from a MIST-like track of initial mass m0 at the time t0.

Return type:

float

match_to_single_star(star, htrack)

Get the track in the grid that matches the time and mass of a star.

For “root” matching_method, the properties that are matched is always the mass of the secondary star. If the secondary has the state MS then the center hydrogen abundance will also be matched otherwise the mass of helium-core will be matched.

Parameters:

star (SingleStar) – The star which properties are required to be matched with the single MIST-like grid.

Returns:

Contains the associated (in solar units) and the time (in years) such that the time-series in the grid matches the properties of the secondary.

Return type:

list of 2 float values

scale(key, htrack, method)

Nomarlize quantities in the single star grids to (0,1).

Parameters:

• key (str) – Keyword of the required quantity.

• method (str) – Scalling method in the data normalization class

Returns:

Data normalization class

Return type:

class

square_difference(x, htrack, mesa_labels, posydon_attributes, colscalers, scales)

Compute the square distance used for scaling.

posydon.binary_evol.DT.step_detached.diffeq(t, y, R_sec, L_sec, M_sec, Mdot_sec, I_sec, conv_mx1_top_r_sec, conv_mx1_bot_r_sec, surface_h1_sec, center_h1_sec, M_env_sec, DR_env_sec, Renv_middle_sec, Idot_sec, tau_conv_sec, R_pri, L_pri, M_pri, Mdot_pri, I_pri, conv_mx1_top_r_pri, conv_mx1_bot_r_pri, surface_h1_pri, center_h1_pri, M_env_pri, DR_env_pri, Renv_middle_pri, Idot_pri, tau_conv_pri, do_wind_loss=True, do_tides=True, do_gravitational_radiation=True, do_magnetic_braking=True, magnetic_braking_mode='RVJ83', do_stellar_evolution_and_spin_from_winds=True, verbose=False)

Diff. equation describing the orbital evolution of a detached binary.

The equation handles wind mass-loss [1], tidal [2], gravational [3] effects and magnetic braking [4], [5], [6], [7], [8]. It also handles the change of the secondary’s stellar spin due to its change of moment of intertia and due to mass-loss from its spinning surface. It is assumed that the mass loss is fully non-conservative. Magnetic braking is fully applied to secondary stars with mass less than 1.3 Msun and fully off for stars with mass larger then 1.5 Msun. The effect of magnetic braking falls linearly for stars with mass between 1.3 Msun and 1.5 Msun.

TODO: exaplin new features (e.g., double COs)

Parameters:

• t (float) – The age of the system in years

• y (list of float) – Contains the separation, eccentricity and angular velocity, in Rsolar, dimensionless and rad/year units, respectively.

• M_pri (float) – Mass of the primary in Msolar units.

• M_sec (float) – Mass of the secondary in Msolar units.

• Mdot (float) – Rate of change of mass of the star in Msolar/year units. (Negative for wind mass loss.)

• R (float) – Radius of the star in Rsolar units.

• I (float) – Moment of inertia of the star in Msolar*Rsolar^2.

• tau_conv (float) – Convective turnover time of the star, calculated @ 0.5*pressure_scale_height above the bottom of the outer convection zone in yr.

• L (float) – Luminosity of the star in solar units.

• #mass_conv_core (float)

• units. (# Convective core mass of the secondary in Msolar)

• conv_mx1_top_r (float) – Coordinate of top convective mixing zone coordinate in Rsolar.

• conv_mx1_bot_r (float) – Coordinate of bottom convective mixing zone coordinate in Rsolar.

• surface_h1 (float) – surface mass Hydrogen abundance

• center_h1 (float) – center mass Hydrogen abundance

• M_env (float) – mass of the dominant convective region for tides above the core, in Msolar.

• DR_env (float) – thickness of the dominant convective region for tides above the core, in Rsolar.

• Renv_middle (float) – position of the dominant convective region for tides above the core, in Rsolar.

• Idot (float) – Rate of change of the moment of inertia of the star in Msolar*Rsolar^2 per year.

• do_wind_loss (Boolean) – If True, take into account change of separation due to mass loss from the secondary. Default: True.

• do_tides (Booleans) – If True, take into account change of separation, eccentricity and secondary spin due to tidal forces. Default: True.

• do_gravitational_radiation (Boolean) – If True, take into account change of separation and eccentricity due to gravitational wave radiation. Default: True

• do_magnetic_braking (Boolean) – If True, take into account change of star spin due to magnetic braking. Default: True.

• magnetic_braking_mode (String) –

  A string corresponding to the desired magnetic braking prescription.

  • RVJ83 : Rappaport, Verbunt, & Joss 1983 [4]

  • M15 : Matt et al. 2015 [5]

  • G18 : Garraffo et al. 2018 [6]

  • CARB : Van & Ivanova 2019 [7]

• do_stellar_evolution_and_spin_from_winds (Boolean) – If True, take into account change of star spin due to change of its moment of inertia during its evolution and due to spin angular momentum loss due to winds. Default: True.

• verbose (Boolean) – If we want to print stuff. Default: False.

Returns:

Contains the change of the separation, eccentricity and angular velocity, in Rsolar, dimensionless and rad/year units, respectively.

Return type:

list of float

References

[1]

Tauris, T. M., & van den Heuvel, E. 2006, Compact stellar X-ray sources, 1, 623

[2]

Hut, P. 1981, A&A, 99, 126

[3]

Junker, W., & Schafer, G. 1992, MNRAS, 254, 146

[4] (1,2)

Rappaport, S., Joss, P. C., & Verbunt, F. 1983, ApJ, 275, 713

[5] (1,2)

Matt et al. 2015, ApJ, 799, L23

[6] (1,2)

Garraffo et al. 2018, ApJ, 862, 90

[7] (1,2)

Van & Ivanova 2019, ApJ, 886, L31

[8]

Gossage et al. 2021, ApJ, 912, 65

posydon.binary_evol.DT.step_detached.event(terminal, direction=0)

Return a helper function to set attributes for solve_ivp events.

posydon.binary_evol.DT.step_disrupted

Merging and isolated evolution step.

class posydon.binary_evol.DT.step_disrupted.DisruptedStep(grid_name_Hrich=None, grid_name_strippedHe=None, path=PATH_TO_POSYDON_DATA, *args, **kwargs)

Bases: IsolatedStep

Prepare a runaway star to do an an isolated_step)

Initialize the step. See class documentation for details.

posydon.binary_evol.DT.step_initially_single

Merging and isolated evolution step.

class posydon.binary_evol.DT.step_initially_single.InitiallySingleStep(grid_name_Hrich=None, grid_name_strippedHe=None, path=PATH_TO_POSYDON_DATA, *args, **kwargs)

Bases: IsolatedStep

Prepare a runaway star to do an an isolated_step)

Initialize the step. See class documentation for details.

posydon.binary_evol.DT.step_isolated

Isolated evolution step.

class posydon.binary_evol.DT.step_isolated.IsolatedStep(grid_name_Hrich=None, grid_name_strippedHe=None, path=PATH_TO_POSYDON_DATA, do_wind_loss=False, do_tides=False, do_gravitational_radiation=False, do_magnetic_braking=False, *args, **kwargs)

Bases: detached_step

Evolve an isolated star (a single star, a merger product, a runaway star, etc.)

The star will be matched in the beginning of the step and will be evolved until core-collapse or maximum simulation time, based on a grid of single star HDF5 grid.

Initialize the step. See class documentation for details.

initialize_isolated_binary_orbit(binary)

re_erase_isolated_binary_orbit(binary)

posydon.binary_evol.DT.step_merged

Merging and isolated evolution step.

class posydon.binary_evol.DT.step_merged.MergedStep(grid_name_Hrich=None, grid_name_strippedHe=None, path=PATH_TO_POSYDON_DATA, merger_critical_rot=0.4, rel_mass_lost_HMS_HMS=0.1, list_for_matching_HMS=[['mass', 'center_h1', 'he_core_mass'], [20.0, 1.0, 10.0], ['log_min_max', 'min_max', 'min_max'], [None, None], [0, None]], list_for_matching_postMS=[['mass', 'center_he4', 'he_core_mass'], [20.0, 1.0, 10.0], ['log_min_max', 'min_max', 'min_max'], [None, None], [0, None]], list_for_matching_HeStar=[['he_core_mass', 'center_he4'], [10.0, 1.0], ['min_max', 'min_max'], [None, None], [0, None]], *args, **kwargs)

Bases: IsolatedStep

Prepare a merging star to do an an IsolatedStep

Initialize the step. See class documentation for details.

merged_star_properties(star_base, comp)

Make assumptions about the core/total mass, and abundances of the star of a merged product.

Similar to the table of merging in BSE

star_base: Single Star

is our base star that engulfs its companion. The merged star will have this star as a base

comp: Single Star

is the star that is engulfed