posydon.binary_evol.DT

• posydon.binary_evol.DT.gravitational_radiation
• posydon.binary_evol.DT.magnetic_braking
• posydon.binary_evol.DT.tides
• posydon.binary_evol.DT.winds

posydon.binary_evol.DT.double_CO

Detached evolution for double compact-object binaries.

class posydon.binary_evol.DT.double_CO.DoubleCO(**kwargs)

Bases: detached_step

Evolve a double compact-object binary due to gravitational radiation.

The binary will be evolved until the two compact objects come into contact or until maximum simulation time, based on the quadrupole approximation of gravitational radiation. The integration is performed in dimensionless variables to guarantee numerical stability.

Initialize the step. See class documentation for details.

solve_ODEs(binary, primary, secondary)

Solve the Peters (1964) GW inspiral.

We do two transformations to the standard Peters equations: 1. We remove the dimensionality by using the dimensionless separation lpha = a/a0 and

dimensionless time au = t / t0, where a0 is the initial separation and t0 is the characteristic GW timescale.

2. We then substitute s = -ln(lpha) to eliminate the singularity in the Peters equations, which removes the alpha^-3 and alpha^-4 prefactors that cause numerical issues for tight binaries.

class posydon.binary_evol.DT.double_CO.double_CO_evolution(**kwargs)

Bases: detached_evolution

Evolution object for double compact-object binaries.

Only gravitational radiation is active; tides, winds, and magnetic braking are disabled. The actual ODE right-hand side is defined as a dimensionless local function inside DoubleCO.solve_ODEs; this class exists so that the detached_step pipeline (track matching, property updates) has a valid evo object.

rhs(s, y)

Right-hand side of the ODE system in ln-space.

Parameters:

• s (float) – Independent variable, s = -ln(a/a0).

• y (array_like) – State vector at s, [l, tau, secondary.omega, primary.omega], where l = ln(e).

posydon.binary_evol.DT.step_detached

Detached evolution step.

class posydon.binary_evol.DT.step_detached.detached_evolution(primary=None, secondary=None, do_wind_loss=True, do_tides=True, do_magnetic_braking=True, magnetic_braking_mode='RVJ83', do_stellar_evolution_and_spin_from_winds=True, do_gravitational_radiation=True, verbose=False)

Bases: object

ODE system describing the evolution of a detached binary.

This class defines the differential equations governing the orbital evolution and stellar spin evolution of a detached binary system. It is designed to be passed directly to scipy.integrate.solve_ivp, with __call__ returning the derivatives of the system state.

The evolution can include contributions from several physical processes:

• Stellar wind mass loss

• Tidal interactions

• Magnetic braking

• Gravitational wave radiation

• Spin evolution from stellar winds and structural changes

The stellar properties required for these calculations are obtained from interpolated single-star evolution tracks associated with the SingleStar objects (binary components) and their PChipInterpolator2 objects.

Parameters:

• primary (SingleStar, optional) – Primary star of the binary (typically the more evolved star). These must have an interp1d interpolator to return stellar properties as a function of time.

• secondary (SingleStar, optional) – Secondary star of the binary.

• do_wind_loss (bool, optional) – If True, include orbital evolution due to stellar wind mass loss.

• do_tides (bool, optional) – If True, include tidal interactions affecting orbital separation, eccentricity, and stellar spin.

• do_magnetic_braking (bool, optional) – If True, include stellar spin evolution due to magnetic braking.

• magnetic_braking_mode ({"RVJ83", "M15", "G18", "CARB"}, optional) –

  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 (bool, optional) – If True, include spin evolution caused by stellar structural evolution and angular momentum loss from winds.

• do_gravitational_radiation (bool, optional) – If True, include orbital evolution from gravitational wave emission.

• verbose (bool, optional) – If True, print diagnostic information during the integration.

primary

Primary star used in the evolution.

Type:

SingleStar

secondary

Secondary star used in the evolution.

Type:

SingleStar

a

Current orbital separation (solar radii).

Type:

float

e

Current orbital eccentricity.

Type:

float

phys_keys

Names of stellar quantities tracked from the interpolated stellar evolution models.

Type:

list of str

t

Current system age during integration.

Type:

float

Notes

The system state vector y evolved by solve_ivp is defined as:

y = [a, e, omega_secondary, omega_primary]

where

• a is the orbital separation (R☉)

• e is the orbital eccentricity

• omega_secondary is the spin angular velocity of the secondary (rad/yr)

• omega_primary is the spin angular velocity of the primary (rad/yr)

Event functions defined in this class detect important transitions such as Roche-lobe overflow or reaching the end of a stellar evolution track.

ev_max_time1(t, y)

ev_max_time2(t, y)

ev_rel_rlo1(t, y)

Relative difference between radius and Roche lobe. Used to

check if there is RLOF mass transfer during the detached binary evolution interpolation. Calculated for the secondary.

Parameters:

• t (float) – Time of the evolution, in years.

• y (tuple(float)) – [separation, eccentricity] at that time. Separation should be in solar radii.

• primary (SingleStar object) – A single star object, representing the primary (more evolved) star in the binary and containing its properties.

• secondary (SingleStar object) – A single star object, representing the secondary (less evolved) star in the binary and containing its properties.

Returns:

RL_rel_diff – Relative difference between stellar radius and Roche lobe radius.

Return type:

float

ev_rel_rlo2(t, y)

Relative difference between radius and Roche lobe. Used to

check if there is RLOF mass transfer during the detached binary evolution interpolation. Calculated for the primary.

Parameters:

• t (float) – Time of the evolution, in years.

• y (tuple(float)) – [separation, eccentricity] at that time. Separation should be in solar radii.

• primary (SingleStar object) – A single star object, representing the primary (more evolved) star in the binary and containing its properties.

• secondary (SingleStar object) – A single star object, representing the secondary (less evolved) star in the binary and containing its properties.

Returns:

RL_rel_diff – Relative difference between stellar radius and Roche lobe radius.

Return type:

float

ev_rlo1(t, y)

Difference between radius and Roche lobe at a given time. Used

to check if there is RLOF mass transfer during the detached binary evolution interpolation. Calculated for the secondary.

Parameters:

• t (float) – Time of the evolution, in years.

• y (tuple(float)) – [separation, eccentricity] at that time. Separation should be in solar radii.

• primary (SingleStar object) – A single star object, representing the primary (more evolved) star in the binary and containing its properties.

• secondary (SingleStar object) – A single star object, representing the secondary (less evolved) star in the binary and containing its properties.

Returns:

RL_diff – Difference between stellar radius and 95% of the Roche lobe radius in solar radii.

Return type:

float

ev_rlo2(t, y)

Difference between radius and Roche lobe at a given time. Used

to check if there is RLOF mass transfer during the detached binary evolution interpolation. Calculated for the primary.

Parameters:

• t (float) – Time of the evolution, in years

• y (tuple(float)) – [separation, eccentricity] at that time. Separation should be in solar radii.

• primary (SingleStar object) – A single star object, representing the primary (more evolved) star in the binary and containing its properties.

• secondary (SingleStar object) – A single star object, representing the secondary (less evolved) star in the binary and containing its properties.

Returns:

RL_diff – Difference between stellar radius and 95% of the Roche lobe radius in solar radii.

Return type:

float

gravitational_radiation()

magnetic_braking()

sep_from_winds()

set_stars(primary, secondary, t0=0.0)

Sets memory references for primary and secondary star associated with this evolution. It is expected that primary/secondary have interp1d objects already, as required for detached evolution.

Parameters:

• primary (SingleStar object) – A single star object, representing the primary (more evolved) star in the binary and containing its properties.

• secondary (SingleStar object) – A single star object, representing the secondary (less evolved) star in the binary and containing its properties.

• t0 (float) – The time at the start of detached evolution. Typically should be the binary.time prior to detached evolution.

spin_from_winds()

tides()

update_props(t, y)

Update properties of stars w/ current age during detached evolution.

This uses the interp1d objects (PchipInterpolator2) of the primary and secondary to interpolate stellar properties using the current time of integration, t, along a stellar track. Compact objects have no stellar track to interpolate along, and simply either have copies of the surviving star, or array-like, zeroed arrays.

The primary and secondary (SingleStar objects) are each given a new

attribute called latest that is a dictionary containing the stellar properties of the star at the latest time of integration, t, for access in calculations during step_detached evolution.

Parameters:

• t (float) – The current time of integration during solve_ivp().

• y (list) – The current set of solutions for orbital separation [Rsol],

• eccentricity (orbital)

• [rad/yr] (spin of the secondary star)

• and

• [rad/yr]. (spin of the primary star)

class posydon.binary_evol.DT.step_detached.detached_step(**kwargs)

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:

• 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 because 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.

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

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

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

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

• magnetic_braking_mode (str) –

  A string corresponding to the desired magnetic braking prescription.

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

• do_stellar_evolution_and_spin_from_winds (bool) – 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.

• RLO_orbit_at_orbit_with_same_am (bool) – Binaries are circularized instaneously when RLO occurs and this option dictates how that is handled. If False (default), place the binary in an orbit with separation equal to the binary’s separation at periastron. If True, circularize the orbit assuming that angular momentum is conserved w.r.t. the previously (possibly) eccentric orbit. In the latter case, the star may no longer fill its Roche lobe after circularization, and may be further evolved until RLO commences once again, but without changing the orbit.

• track_matcher (TrackMatcher object) – The TrackMatcher object performs functions related to matching binary stellar evolution components to single star evolution models.

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

KEYS

Contains keywords corresponding to MESA data column names which are used to extract quantities from the single star evolution grids.

Type:

list[str]

translate

Dictionary containing data column name (key) translations between POSYDON h5 file PSyGrid data names (items) and MESA data names (keys).

Type:

dict

evo

Handler object responsible for performing the detached binary evolution.

Type:

detached_evolution

evo_kwargs

Keyword arguments used to initialize detached_evolution.

Type:

dict

Initialize the step. See class documentation for details.

DEFAULT_KWARGS = {'RLO_orbit_at_orbit_with_same_am': False, 'RNG': Generator(PCG64) at 0x7FB8CB0E4E40, 'do_gravitational_radiation': True, 'do_magnetic_braking': True, 'do_stellar_evolution_and_spin_from_winds': True, 'do_tides': True, 'do_wind_loss': True, 'dt': None, 'magnetic_braking_mode': 'RVJ83', 'metallicity': None, 'n_o_steps_history': None, 'track_matcher': None, 'verbose': False}

get_time_after_evo(binary)

After detached evolution, this uses the ODESolver result

to determine what the current time is.

Parameters:

• res (ODESolver object) – This is the ODESolver object produced by SciPy’s solve_ivp function that contains calculated values of the stars evolution through the detached step.

• binary (BinaryStar object) – A binary star object, containing the binary system’s properties.

Returns:

t – This is the time elapsed as a result of detached evolution in years. This is a float unless the user specifies a timestep (see n_o_steps_history or dt) to use via the simulation properties ini file, in which case it is an array.

Return type:

float or array[float]

init_evo_kwargs()

Store keyword args required to initialize detached evolution, based on step’s kwargs.

solve_ODEs(binary, primary, secondary)

Utilizes SciPy’s solve_ivp() method to solve a set of

differential equations that describe the orbital evolution (separation and eccentricity) and stellar rotation rate evolution during step_detached.

Parameters:

• binary (BinaryStar object) – A binary star object, containing the binary system’s properties.

• primary (SingleStar object) – A single star object, representing the primary (more evolved) star in the binary and containing its properties.

• secondary (SingleStar object) – A single star object, representing the secondary (less evolved) star in the binary and containing its properties.

Returns:

res – This is the ODESolver object produced by SciPy’s solve_ivp function that contains calculated values of the stars evolution through the detached step.

Return type:

ODESolver object

update_after_evo(t, binary, primary, secondary)

Update star and binary properties and interpolators with

ODESolver result from detached evolution. This update gives the binary/stars their appropriate values, according to the interpolation after detached evolution.

Parameters:

• t (float or array[float]) – This is the time elapsed as a result of detached evolution in years. This is a float unless the user specifies a timestep to use via the simulation properties ini file, in which case it is an array.

• binary (BinaryStar object) – A binary star object, containing the binary system’s properties.

• primary (SingleStar object) – A single star object, representing the primary (more evolved) star in the binary and containing its properties.

• secondary (SingleStar object) – A single star object, representing the secondary (less evolved) star in the binary and containing its properties.

Warns:

InappropriateValueWarning – If trying to compute log angular momentum for object with no spin.

update_co_stars(t, primary, secondary)

Update compact object properties after detached

evolution. The properties are updated here using the CO star properties from the last step. Often, these values are null.

Parameters:

• t (float or array[float]) – This is the time elapsed as a result of detached evolution in years. This is a float unless the user specifies a timestep to use via the simulation properties ini file, in which case it is an array.

• primary (SingleStar object) – A single star object, representing the primary (more evolved) star in the binary and containing its properties.

• secondary (SingleStar object) – A single star object, representing the secondary (less evolved) star in the binary and containing its properties.

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(*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(*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(*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(merger_critical_rot=0.4, rel_mass_lost_HMS_HMS=0.1, *args, **kwargs)

Bases: IsolatedStep

Prepare a merging star to do an an IsolatedStep

Initialize the step. See class documentation for details.

mass_weighted_avg(star1, star2, abundance_name, mass_weight1='mass', mass_weight2='mass')

Compute the mass-weighted average of an abundance between two stars.

Parameters:

• star1 (SingleStar) – Primary star

• star2 (SingleStar) – Companion star

• abundance_name (str) – Name of the SingleStar attribute to average.

• mass_weight1 (str) – Mass attribute to use as weight for star1. Special values "H-rich_envelope_mass" and "He-rich_envelope_mass" are computed on the fly; any other value is looked up directly on the star object.

• mass_weight2 (str or None) – Mass attribute for star2.

merged_star_properties(star_base, comp)

Set the properties of the merged star after a merger event.

Generally, the Roche lobe overflowing star becomes star_base, except when the companion is further evolved than star_base, in which case the comp becomes the base for the merged star.

Abundances are mass-weighted averages of the two stars, with the weights depending on the type of merger and the abundance considered.

star_base: Single Star

The star that engulfs its companion. (generally the base for the merged_star)

comp: Single Star

The star that is engulfed by star_base.