# useful_funcs module

Collection of useful functions.

Part of this is copied/inspired by Rob’s binary_stars module

Functions:

  - calc_period_from_sep(m1, m2, sep) calculate the period given the separation.

  - calc_sep_from_period(m1, m2, per) does the inverse.

  - rzams(m, z) gives you the ZAMS radius of a star

  - ZAMS_collision(m1, m2, e, sep, z) returns 1 if stars collide on the ZAMS

  - roche_lobe(q): returns roche lobe radius in units of separation

  - ragb(m, z): radius at first thermal pulse

  - minimum_period_for_RLOF(M1, M2, metallicity, store_memaddr=-1): function to calculate the minimum period that leads to RLOF on ZAMS

  - minimum_separation_for_RLOF(M1, M2, metallicity, store_memaddr=-1): function to calculate the minimum period that leads to RLOF on ZAMS

  - maximum_mass_ratio_for_RLOF(M1, orbital_period, store_memaddr=None): Function to calculate the maximum mass ratio that leads to RLOF on ZAMS

Tasks:

  - TODO: check whether these functions are correct

  - TODO: add unit test for maximum_mass_ratio_for_RLOF

`binarycpython.utils.useful_funcs.``calc_period_from_sep`(M1, M2, sep)

  calculate period from separation

  Parameters

    - M1 (`Union`[`int`, `float`]) – Primary mass in solar mass

    - M2 (`Union`[`int`, `float`]) – Secondary mass in solar mass

    - sep (`Union`[`int`, `float`]) – Separation in solar radii

  Return type

    `Union`[`int`, `float`]

  Returns

    period in days

`binarycpython.utils.useful_funcs.``calc_sep_from_period`(M1, M2, period)

  Calculate separation from period.

  Parameters

    - M1 (`Union`[`int`, `float`]) – Primary mass in solar mass

    - M2 (`Union`[`int`, `float`]) – Secondary mass in solar mass

    - period (`Union`[`int`, `float`]) – Period of binary in days

  Return type

    `Union`[`int`, `float`]

  Returns

    Separation in solar radii

`binarycpython.utils.useful_funcs.``maximum_mass_ratio_for_RLOF`(M1, orbital_period, metallicity=0.02, store_memaddr=None)

  Wrapper function for _binary_c_bindings.return_maximum_mass_ratio_for_RLOF

  Handles the output and returns the maximum mass ratio at which RLOF just does not occur at ZAMS

  Parameters

    - M1 – Primary mass in solar mass

    - orbital_period – orbital period in days

    - metallicity – metallicity

    - store_memaddr (optional) – store memory adress

  Returns

    maximum mass ratio that just does not cause a RLOF at ZAMS

`binarycpython.utils.useful_funcs.``minimum_period_for_RLOF`(M1, M2, metallicity, store_memaddr=- 1)

  Wrapper function for _binary_c_bindings.return_minimum_orbit_for_RLOF

  Handles the output and returns the minimum orbital period at which RLOF just does not occur at ZAMS

  Parameters

    - M1 – Primary mass in solar mass

    - M2 – Secondary mass in solar mass

    - metallicity – metallicity

    - store_memaddr (optional) – store memory address

  Returns

    minimum orbital_period that just does not cause a RLOF at ZAMS

`binarycpython.utils.useful_funcs.``minimum_separation_for_RLOF`(M1, M2, metallicity, store_memaddr=- 1)

  Wrapper function for _binary_c_bindings.return_minimum_orbit_for_RLOF

  Handles the output and returns the minimum separation at which RLOF just does not occur at ZAMS

  Parameters

    - M1 – Primary mass in solar mass

    - M2 – Secondary mass in solar mass

    - metallicity – metallicity

    - store_memaddr (optional) – store memory adress

  Returns

    minimum separation that just does not cause a RLOF at ZAMS

`binarycpython.utils.useful_funcs.``ragb`(m, z)

  Function to calculate radius of a star in units of solar radii at first thermal pulse as a function of mass (Z=0.02 only, but also good for Z=0.0001)

  TODO: ask rob about this function

  Parameters

    - m (`Union`[`int`, `float`]) – mass of star in units of solar mass

    - z (`Union`[`int`, `float`]) – metallicity of star

  Return type

    `Union`[`int`, `float`]

  Returns

    radius at first thermal pulse in units of solar radii

`binarycpython.utils.useful_funcs.``roche_lobe`(q)

  A function to evaluate R_L/a(q), Eggleton 1983.

  # TODO: check the definition of the mass ratio # TODO: check whether the logs are correct

  Parameters

    q (`Union`[`int`, `float`]) – mass ratio of the binary (secondary/primary). If you input: q = mass_accretor/mass_donor, you will get the rochelobe radius of the accretor. And vice versa for the donor.

  Return type

    `Union`[`int`, `float`]

  Returns

    Roche lobe radius in units of the separation

`binarycpython.utils.useful_funcs.``rzams`(m, z)

  Function to determine the radius of a ZAMS star as a function of m and z:

  Based on the fits of Tout et al., 1996, MNRAS, 281, 257

  Parameters

    - m – mass of star in solar mass

    - z – metallicity

  Returns

    radius of star at ZAMS, in solar radii

`binarycpython.utils.useful_funcs.``zams_collision`(m1, m2, sep, e, z)

  given m1,m2, separation and eccentricity (and metallicity) determine if two stars collide on the ZAMS

  Parameters

    - m1 (`Union`[`int`, `float`]) – Primary mass in solar mass

    - m2 (`Union`[`int`, `float`]) – Secondary mass in solar mass

    - sep (`Union`[`int`, `float`]) – separation in solar radii

    - e (`Union`[`int`, `float`]) – eccentricity

    - z (`Union`[`int`, `float`]) – metallicity

  Return type

    `Union`[`int`, `float`]

  Returns

    integer boolean whether the binary stars will collide at pericenter