The BinaryStar object

The BinaryStar object is composed of two SingleStar objects (see The SingleStar object) and contains the current and past states of the binary. Only parameters in the BINARYPROPERTIES list are stored in the history. The current parameter value of the star object is accessed with, e.g. binary.orbital_period and the past history via binary.orbital_period_history. The two stars are accessed with, e.g. (for star 1), binary.star_1.mass and the past history via binary.star_1.mass_history.

To use BinaryStar object import it using:

from posydon.binary_evol.singlestar import SingleStar
from posydon.binary_evol.binarystar import BinaryStar

Creating a BinaryStar object

BINARYPROPERTIES

The binary properties are defined as follows

BINARYPROPERTIES
Properties	Descriptions
`state`	The state of the binary, see state options.
`event`	The event of the binary, see event options.
`time`	Age of the binary system in yr.
`separation`	Orbital separation in R_sun.
`orbital_period`	Orbital period in days.
`eccentricity`	Orbital eccentricity.
`V_sys`	Velocity of the centre of mass of the binary [Vx, Vy, Vz] in km/s.
`mass_transfer_case`	Mass transfer case, see MT case options.
`lg_mtransfer_rate`	The logarithm of the mass transfer rate in Msun/yr.
`step_names`	Names of the steps in the evolution.
`step_times`	Time spent in the steps in the evolution.
`rl_relative_overflow_1`	The relative overflow of the Roche Lobe of star 1.
`rl_relative_overflow_2`	The relative overflow of the Roche Lobe of star 2.
`trap_radius`	The trapping radius of the binary in R_sun.
`acc_radius`	The accretion radius of the binary in R_sun.
`t_sync_rad_1`	The synchronization time of the radiative zone of star 1 in yr.
`t_sync_conv_1`	The synchronization time of the convective zones of star 1 in yr.
`t_sync_rad_2`	The synchronization time of the radiative zone of star 2 in yr.
`t_sync_conv_2`	The synchronization time of the convective zones of star 2 in yr.
`nearest_neighbour_distance`	The distance to the nearest neighbour for NN interpolation

Additional scalar properties can be added during the evolution.

Since they do not change over time, they are not stored in the history. These can be requested and will be stored in the output oneline (See the Synthetic Population and Population Parameter Guide for more information).

Additional columns

The additional columns are defined as follows:

Additional columns
Properties	Descriptions
`interp_class_HMS_HMS`	The interpolation class for the HMS_HMS phase.
`interp_class_CO_HMS_RLO`	The interpolation class for the CO_HMS_RLO phase.
`interp_class_CO_HeMS`	The interpolation class for the CO_HeMS phase.
`interp_class_CO_HeMS_RLO`	The interpolation class for the CO_HeMS_RLO phase.
`mt_history_HMS_HMS`	The mass transfer history for the HMS_HMS phase.
`mt_history_CO_HMS_RLO`	The mass transfer history for the CO_HMS_RLO phase.
`mt_history_CO_HeMS`	The mass transfer history for the CO_HeMS phase.
`mt_history_CO_HeMS_RLO`	The mass transfer history for the CO_HeMS_RLO phase.

State options

Binary states are defined according to the following table:

States
State	Description
`initially_single_star`	The binary was initially a single star.
`detached`	The stars in the binary are in a detached state.
`RLO1`	The binary is Roche Lobe overflowing, star 1 is overfilling the RL.
`RLO2`	The binary is Roche Lobe overflowing, star 2 is overfilling the RL.
`contact`	The stars in the binary are in contact.
`disrupted`	The binary was disrupted.
`merged`	The stars in the binary merged.
`initial_RLOF`	The binary is in the initial Roche Lobe overflow.
`maxtime`	Max time of the evolution was reached.
`FAILED`	The evolution failed.

Event options

Binary events are defined according to the following table:

Mass Transfer case

The mass transfer cases are stored in mt_history_GRIDTYPE and are defined according to the following table: TODO: add the table below

Mass transfer cases
Case	Description
`None`	The binary is not Roche Lobe overflowing.

TODO: update properties

Basic example

The simplest method is to provide the two star objects and kwargs of the initial binary parameters.

kwargs1 = {'state' : 'MS',
           'mass' : 20.0,
           'metallicity' : 0.014}

star_1 = SingleStar(**kwargs1)

kwargs2 = {'state' : 'MS',
           'mass' : 10.0,
           'metallicity' : 0.014}

star_2 = SingleStar(**kwargs2)

kwargs3 = {'state' : 'detached',
           'event' : None,
           'time' : 0.,
           'orbital_period' : 3.,
           'eccentricity' : 0.}


binary = BinaryStar(star_1, star_2, **kwargs3)