poskiorb package

poskiorb.binary module

class poskiorb.binary.BinarySystem(m1: float, m1_core_mass: float, m1_fallback_fraction: float, m1_remnant_mass: float, m2: float, P: Optional[float] = None, a: Optional[float] = None)[source]

Bases: object

Class containing the status of a binary system at core-collapse

It contains information on the binary such as orbital period, separation, eccentricty and masses, but also holds information of the collapsing star (core mass, fallback fraction and remnant mass). All this is then used to populate the post-collapse binary parameters 2D grid of period/separation and eccentricity assuming an instantaneous asymmetric kick distribution

Parameters:

  • m1 (float) – Mass of the collapsing star in Msun units.

  • m1_core_mass (float) – Mass of the carbon-oxygen core of the collapsing star in Msun units.

  • m1_fallback_fraction (float) – Fraction of mass that fallsback during core-collapse to the compact object.

  • m1_remnant_mass (float) – Remnant mass of the compact object left after core-collapse in Msun units.

  • m2 (float) – Mass of the companion star in Msun units.

  • P (float) – Binary orbital period just before collapse (either P or a must be supplied) in days units.

  • a (float) – Binary separation just before collapse (either a or P must be supplied) in Rsun units.

Variables:

f_orb (float) – Orbital frequency just before collapse in units of frequency

get_natal_kick_distribution() → None[source]

Compute random asymmetric natal kicks from a given distribution

The orientation of the kick, controlled by the (theta, phi) variables, is assumed to be isotropically distributed

get_orbital_distribution(verbose: bool = False) → None[source]

Evaluate orbital parameter distribution based on a distribution of natal kicks

Parameters:

verbose (boolean) – Flag to control the output of additional info to user

get_post_kick_grid(xnum: int = 10, ynum: int = 10, xquantiles: Tuple[float, float] = [0.05, 0.95], yquantiles: Tuple[float, float] = [0.0, 1.0], min_prob: float = 0.01, use_unbounded_for_norm: bool = False, verbose: bool = False) → None[source]

Compute a 2D grid of orbital configurations of binaries surviving asymmetric kicks

Based on two arrays of the same length, it divides the 2D plane into rectangular grids, computes the probability of each rectangle (MonteCarlo approach, a simple summation) and returns the grid and the probabilities.

Parameters:

  • xnum (integer) – Number of bins for the xattr

  • ynum (integer) – Number of bins for the yattr

  • xquantiles (array) – Compute bins on xaxis between (xquantiles[0], xquantiles[1])

  • yquantiles (array) – Compute bins on yaxis between (yquantiles[0], yquantiles[1])

  • min_prob (float) – Minimum probability value to consider it a possible candidate rectangle to further explore with a detailed evolutionary simulation. Default: 1% (min_prob=0.01)

  • use_unbounded_for_norm (boolean) – Whether to consider the complete sample of binaries when evaluating probabilities

  • verbose (boolean) – Output more information for user

plot_kick_distribution(xattr: str, **kwargs) → None[source]

Plot utility for natal kick distributions (w, theta, phi)

Parameters:

  • xattr (string) – Name of variable to plot on xaxis

  • **kwargs (various) – Contains additional stuff to make histogram/KDE of kick distributions

plot_post_kick_orbital_configurations(xattr: str, yattr: str, **kwargs) → Tuple[Any, Any][source]

TBD

save_border_grid(fname: str = 'borders.data') → None[source]

TBD

save_complete_grid(kick_fname: str = 'kick-distribution.data', orbit_fname: str = 'orbit.data') → None[source]

TBD

save_target_grid(fname: str = 'grid.data') → None[source]

Save orbital parameters conforming 2D grid of Porb (or separation) and e

It contains a header with the following columns:

# asymmetric natal-kick id orbital period [days] separation [Rsun] eccentricity

It saves some info on the distribution used for the natal kicks with important values. In addition, the probability set to define grid is also present

Parameters:

fname (str) – Name of file where data will be saved.

set_natal_kick_distribution(n_trials: int = 1, distribution_id: ~typing.Optional[str] = None, seed: int = 22, kick_sigma: float = 265.0, min_v_kick: float = 0.0, max_v_kick: float = 1e+99, kick_scaling: ~typing.Callable[[~typing.Any], ~typing.Any] = <function BinarySystem.<lambda>>) → None[source]

Set distribution in the magnitude of the natal kick

The angle distribution of the asymmetric natal kick is assumed to be isotropic

Parameters:

  • n_trials (integer) – Number of trials to perform draws from a distribution.

  • distribution_id (string) – Name of the distribution of natal kicks.

  • seed (integer) – Seed to start random number generator.

  • kick_sigma (float) – Dispersion velocity for a Maxwellian distribution in km/s.

  • min_v_kick (float) – Min kick velocity in km/s (only used for linearly-spaced and log-spaced cases).

  • max_v_kick (float) – Max kick velocity in km/s (only used for linearly-spaced and log-spaced cases).

  • kick_scaling (function) – Some function to apply to natal kick strength as a scaling factor. Default is to leave kick strength as it is.

show_post_kick_with_grid(xattr: str, yattr: str, min_prob: float = 0.01, **kwargs)[source]

Plot grid of post kick orbital configurations

poskiorb.kicks module

Module that computes natal kicks from certain distributions

Provides values for random kicks directions and strengths according to results from Kalogera, 1996

poskiorb.kicks.kick_velocity_distribution(distribution: Optional[str] = None, N: int = 10000, sigma: float = 265.0, kwargs: dict = {}) → ndarray[source]

Random kick velocity

Parameters:

  • distribution (str) – Name of the probability density function (pdf) to use for natal kicks. Valid options are:

    • Uniform

    • Maxwell

    • Delta

    • Lorentz

    • linearly-spaced

    • log-spaced.

  • N (int) – Number of trials.

  • sigma (float) – Maxwellian dispersion velocity in km/s (also max value for uniform distribution).

Returns:

w (array) – Velocity of natal kick in km/s.

poskiorb.kicks.phi_distribution(N: int = 10000) → ndarray[source]

Function that returns random value for phi angle

Parameters:

N (int) – Number of trials.

Returns:

phi (array) – Azimutal angle of kick. 0 < phi < 2*pi.

poskiorb.kicks.theta_distribution(N: int = 10000) → ndarray[source]

Provides random value for tetha angle

Parameters:

N (int) – Number of trials.

Returns:

theta (array) – Polar angle of kick. 0 < tetha < pi.

poskiorb.utils module

A collection of miscellaneous utility functions

poskiorb.utils.P_to_a(period: Union[float, ndarray], m1: Union[float, ndarray], m2: Union[float, ndarray]) → Union[float, ndarray][source]

Binary separation from a known period

Parameters:

  • period (float/array) – Binary period in days

  • m1 (float/array) – Mass of primary star in Msun

  • m2 (flota/array) – Mass of secondary star in Msun

Returns:

a (float/array) – Binary separation in Rsun

poskiorb.utils.a_to_P(separation: Union[float, ndarray], m1: Union[float, ndarray], m2: Union[float, ndarray]) → Union[float, ndarray][source]

Orbital period from a known separation

Parameters:

  • a (float/array) – Binary separation in Rsun

  • m1 (float/array) – Mass of primary star in Msun

  • m2 (float/array) – Mass of secondary star in Msun

Returns:

P (float/array) – Binary period in days

poskiorb.utils.a_to_f(separation: Union[float, ndarray], m1: Union[float, ndarray], m2: Union[float, ndarray]) → Union[float, ndarray][source]

Converts semi-major axis to orbital frequency

Parameters:

  • separation (float/array) – Semi-major axis

  • m1 (float/array) – Primary mass

  • m2 (float/array) – Secondary mass

Returns:

f_orb (float/array) – Orbital frequency

poskiorb.utils.binary_orbits_after_kick(a: float, m1: float, m2: float, m1_remnant_mass: float, w: Union[float, ndarray], theta: Union[float, ndarray], phi: Union[float, ndarray], ids: Union[float, ndarray], verbose: bool = False) → Tuple[Union[float, ndarray], Union[float, ndarray], Union[float, ndarray], Union[float, ndarray], Union[float, ndarray], Union[float, ndarray]][source]

Function to compute binary orbital parameters after an asymmetric core-collapse

Assuming an initial circular orbit, this function calculates the binary configuration after a SN explosion with an asymmetric random component. Based on the work of Kalogera (1996)

Parameters:

  • a (float) – Pre-SN separation in Rsun.

  • m1 (float) – Mass of collapsing star pre-SN in Msun.

  • m2 (float) – Mass of companion in Msun.

  • m1_remnant_mass (float) – Gravitational mass of compact object in Msun.

  • w (float/array) – Natal kick velocity in km/s.

  • theta (float/array) – Polar angle of kick.

  • phi (float/array) – Azimutal angle of kick velocity.

  • verbose (bool) – Flag to control additional output to user.

Returns:

  • a_post (float/array) – Post-SN separation in Rsun.

  • P_post (float/array) – Post-SN orbital period in days.

  • e (float/array) – Eccentricity of binary post-SN.

  • cos_i (float/array) – Cosine of the inclination between pre & post SN orbits.

  • v_sys (float/array) – Systemic velocity post-SN in km/s

poskiorb.utils.make_grid_of_orbital_configurations(x, y, z, xrange=[0.05, 0.95], yrange=[0.0, 1.0], xnum=None, ynum=None, norm=None, verbose=False)[source]

Compute probabilities on orbital parameters post natal kick and divide it according to a threshold

Parameters:

  • x (array) – Values on the xaxis. Either P_post or a_post

  • y (array) – Values on the yaxis. Tipically eccentricty (e_post)

  • z (array) – Values on the zaxis. Use for inclination values only (cosi)

  • xrange (array) – Quantiles to use as borders xrange = [xmin, xmax]

  • yrange (array) – Quantiles to use as borders yrange = [ymin, ymax]

  • xnum (int) – Number of grid points in the xaxis

  • ynum (int) – Number of grid points in the yaxis

  • verbose (boolean) – Whether to output more information to user

poskiorb.utils.make_grid_plot(xgrid, ygrid, xborders, yborders, annotations, fig, ax, xlim=None, ylim=None, show=True)[source]

Fill 2D binary parameter space after kick with a grid based on some probability

Parameters:

  • xgrid (array) – X coordinate of center of each rectangle in the grid

  • ygrid (array) – Y coordinate of center of each rectangle in the grid

  • xborders (array) – X coordinate of border of each rectangle in the grid. Sort of bins in xaxis

  • yborders (array) – Y coordinate of border of each rectangle in the grid. Sort of bins in yaxis

  • annotations (array) – What to annotate in (xgrid, ygrid). Tipically np.log10(probability)

  • fig (matplotlib Figure) – A figure on which to plot the distribution. Both ax and fig must be supplied for either to be used

  • ax (matplotlib Axis) – An axis on which to plot the distribution. Both ax and fig must be supplied for either to be used

  • xlim (tuple) – Lower and upper limits for the x axis, passed to Axes.set_xlim()

  • ylim (tuple) – Lower and upper limits for the y axis, passed to Axes.set_ylim()

  • show (boolean) – Whether to immediately show the plot or only return the Figure and Axis

Returns:

  • fig (matplotlib Figure) – The figure on which the distribution is plotted

  • ax (matplotlib Axis) – The axis on which the distribution is plotted

poskiorb.utils.make_scatter_plot(x, y, fig=None, ax=None, xlabel=None, ylabel=None, xlim=None, ylim=None, s=None, color=None, marker=None, show=True, xlogscale=True, ylogscale=False, **kwargs)[source]

make scatter plot

This function is a wrapper for matplotlib.pyplot.scatter(),

Parameters:

  • x (float/int array) – Variable to plot on xaxis, should be a 1D array

  • y (float/int array) – Variable to plot on yaxis, should be a 1D array

  • fig (matplotlib Figure) – A figure on which to plot the distribution. Both ax and fig must be supplied for either to be used

  • ax (matplotlib Axis) – An axis on which to plot the distribution. Both ax and fig must be supplied for either to be used

  • xlabel (string) – Label for the x axis, passed to Axes.set_xlabel()

  • ylabel (string) – Label for the y axis, passed to Axes.set_ylabel()

  • xlim (tuple) – Lower and upper limits for the x axis, passed to Axes.set_xlim()

  • ylim (tuple) – Lower and upper limits for the y axis, passed to Axes.set_ylim()

  • s (integer) – Size of the scatter points

  • color (string or tuple) – Colour to use for the plot, see https://matplotlib.org/tutorials/colors/colors.html for details on how to specify a colour

  • marker (string) – The marker style. See matplotlib.markers for more information about marker styles.

  • show (boolean) – Whether to immediately show the plot or only return the Figure and Axis

  • xlogscale (boolean) – Whether to use log scale on the xaxis

  • ylogscale (boolean) – Whether to use log scale on the yaxis

  • **kwargs ((if disttype==”hist”)) – Include values for any of the rest of arguments to pass to matplotlib scatter. See matplotlib scatter doc for more info.ç

Returns:

  • fig (matplotlib Figure) – The figure on which the distribution is plotted

  • ax (matplotlib Axis) – The axis on which the distribution is plotted

poskiorb.utils.plot_1D_distribution(x, weights=None, disttype='hist', fig=None, ax=None, xlabel=None, ylabel=None, xlim=None, ylim=None, color=None, show=True, **kwargs)[source]

plot a 1D distribution of x

This function is a wrapper for matplotlib.pyplot.hist(), seaborn.kdeplot() and seaborn.ecdfplot().

Copied from the excellent repo The LISA Evolution and Gravitational Wave ORbit Kit All credits goes to authors: https://github.com/katiebreivik/LEGWORK (visualization.py module)

Parameters:

  • x (float/int array) – Variable to plot, should be a 1D array

  • weights (float/int array) – Weights for each variable in x, must have the same shape

  • disttype ({{ “hist”, “kde”, “ecdf” }}) – Which type of distribution plot to use

  • fig (matplotlib Figure) – A figure on which to plot the distribution. Both ax and fig must be supplied for either to be used

  • ax (matplotlib Axis) – An axis on which to plot the distribution. Both ax and fig must be supplied for either to be used

  • xlabel (string) – Label for the x axis, passed to Axes.set_xlabel()

  • ylabel (string) – Label for the y axis, passed to Axes.set_ylabel()

  • xlim (tuple) – Lower and upper limits for the x axis, passed to Axes.set_xlim()

  • ylim (tuple) – Lower and upper limits for the y axis, passed to Axes.set_ylim()

  • color (string or tuple) – Colour to use for the plot, see https://matplotlib.org/tutorials/colors/colors.html for details on how to specify a colour

  • show (boolean) – Whether to immediately show the plot or only return the Figure and Axis

  • **kwargs ((if disttype==”hist”)) – Include values for any of bins, range, density, cumulative, bottom, histtype, align, orientation, rwidth, log, label. See matplotlib.pyplot.hist() for more details.

  • **kwargs ((if disttype==”kde”)) – Include values for any of gridsize, cut, clip, legend, cumulative, bw_method, bw_adjust, log_scale, fill, label, linewidth, linestyle. See seaborn.kdeplot() for more details.

  • **kwargs ((if disttype==”ecdf”)) – Include values for any of stat, complementary, log_scale, legend, label, linewidth, linestyle. See seaborn.edcfplot() for more details.

Returns:

  • fig (matplotlib Figure) – The figure on which the distribution is plotted

  • ax (matplotlib Axis) – The axis on which the distribution is plotted

Module contents