bioverse.functions module

Contains all functions currently used to simulate planetary systems. To define new functions, add them to custom.py.

bioverse.functions.luminosity_evolution(d)

Computes age-dependent luminosities based on the stellar evolution tracks in Baraffe et al. (1998).

Parameters:

d (Table) – Table with stars. Has to have columns for mass and age.

Returns:

d

Return type:

Table containing age-dependent luminosities.

bioverse.functions.read_stars_Gaia(d, filename='gcns_catalog.dat', d_max=120.0, M_st_min=0.075, M_st_max=2.0, R_st_min=0.095, R_st_max=2.15, T_min=0.0, T_max=10.0, inc_binary=0, seed=42, M_G_max=None, lum_evo=True)

Reads a list of stellar properties from the Gaia nearby stars catalog.

Parameters:

  • d (Table) – An empty Table object.

  • filename (str, optional) – Filename containing the Gaia target catalog.

  • d_max (float, optional) – Maximum distance to which to simulate stars, in parsecs.

  • M_st_min (float, optional) – Minimum stellar mass, in solar units.

  • M_st_max (float, optional) – Maximum stellar mass, in solar units.

  • R_st_min (float, optional) – Minimum stellar radius, in solar units.

  • R_st_max (float, optional) – Maximum stellar radius, in solar units.

  • T_min (float, optional) – Minimum stellar age, in Gyr.

  • T_max (float, optional) – Maximum stellar age, in Gyr.

  • inc_binary (bool, optional) – Include binary stars? Default = False.

  • seed (int, optional) – seed for the random number generators.

  • mult (float, optional) – Multiple on the total number of stars simulated. If > 1, duplicates some entries from the LUVOIR catalog.

  • M_G_max (float, optional) – Maximum Gaia magnitude of stars. Example: M_G_max=9. keeps all stars brighter than M_G = 9.0.

  • lum_evo (bool, optional) – Assign age-dependent stellar luminosities (based on randomly assigned ages and stellar luminosity tracks in Baraffe et al. 1998.

Returns:

d – Table containing the sample of real stars.

Return type:

Table

bioverse.functions.create_stars_Gaia(d, d_max=150, M_st_min=0.075, M_st_max=2.0, T_min=0.0, T_max=10.0, T_eff_split=4500.0, seed=42)

Reads temperatures and coordinates for high-mass stars from Gaia DR2. Simulates low-mass stars from the Chabrier+2003 PDMF. Ages are drawn from a uniform distribution, by default from 0 - 10 Gyr. All other stellar properties are calculated using the scaling relations of Pecaut+2013.

Parameters:

  • d (Table) – An empty Table object.

  • d_max (float, optional) – Maximum distance to which to simulate stars, in parsecs.

  • M_st_min (float, optional) – Minimum stellar mass, in solar units.

  • M_st_max (float, optional) – Maximum stellar mass, in solar units.

  • T_min (float, optional) – Minimum stellar age, in Gyr.

  • T_max (float, optional) – Maximum stellar age, in Gyr.

  • T_eff_split (float, optional) – Effective temperature (in Kelvin) below which to simulate stars from a PDMF instead of using Gaia data.

  • seed (int or 1-d array_like, optional) – Seed for numpy’s RandomState. Must be convertible to 32 bit unsigned integers.

Returns:

d – Table containing the sample of simulated stars.

Return type:

Table

bioverse.functions.read_stellar_catalog(d, filename='/home/docs/checkouts/readthedocs.org/user_builds/bioverse/envs/stable/lib/python3.7/site-packages/bioverse-1.1.0-py3.7.egg/bioverse/Data/LUVOIR_targets.dat', d_max=30.0, T_min=0.0, T_max=10.0, mult=1, seed=42)

Reads a list of stellar properties from the LUVOIR target catalog and fills in missing values.

Parameters:

  • d (Table) – An empty Table object.

  • filename (str, optional) – Filename containing the LUVOIR target catalog.

  • d_max (float, optional) – Maximum distance to which to simulate stars, in parsecs.

  • T_min (float, optional) – Minimum stellar age, in Gyr.

  • T_max (float, optional) – Maximum stellar age, in Gyr.

  • mult (float, optional) – Multiple on the total number of stars simulated. If > 1, duplicates some entries from the LUVOIR catalog.

  • seed (int or 1-d array_like, optional) – Seed for numpy’s RandomState. Must be convertible to 32 bit unsigned integers.

Returns:

d – Table containing the sample of simulated stars.

Return type:

Table

bioverse.functions.create_planets_bergsten(d, R_min=1.0, R_max=3.5, P_min=2, P_max=100.0, transit_mode=False, f_eta=1.0, seed=42)

Generates planets with periods and radii according to Bergsten+2022 occurrence rate estimates.

Parameters:

  • d (Table) – Table containing simulated host stars.

  • R_min (float, optional) – Minimum planet radius, in Earth units.

  • R_max (float, optional) – Maximum planet radius, in Earth units.

  • P_min (float, optional) – Minimum orbital period, in days.

  • P_max (float, optional) – Maximum orbital period, in days.

  • transit_mode (bool, optional) – If True, only transiting planets are simulated.

  • f_eta (float, optional) – Occurrence rate scaling factor. The default f_eta = 1 represents the occurrence rates in Bergsten+2022. A different factor will scale the overall occurrence rates accordingly.

  • seed (int or 1-d array_like, optional) – Seed for numpy’s RandomState. Must be convertible to 32 bit unsigned integers.

Returns:

d – Table containing the sample of simulated planets. Replaces the input Table.

Return type:

Table

bioverse.functions.create_planets_SAG13(d, eta_Earth=0.075, R_min=0.5, R_max=14.3, P_min=0.01, P_max=10.0, normalize_SpT=True, transit_mode=False, optimistic=False, optimistic_factor=5, seed=42)

Generates planets with periods and radii according to SAG13 occurrence rate estimates, but incorporating the dependence of occurrence rates on spectral type from Mulders+2015.

Parameters:

  • d (Table) – Table containing simulated host stars.

  • eta_Earth (float, optional) – The number of Earth-sized planets in the habitable zones of Sun-like stars. All occurrence rates are uniformly scaled to produce this estimate.

  • R_min (float, optional) – Minimum planet radius, in Earth units.

  • R_max (float, optional) – Maximum planet radius, in Earth units.

  • P_min (float, optional) – Minimum orbital period, in years.

  • P_max (float, optional) – Maximum orbital period, in years.

  • normalize_SpT (bool, optional) – If True, modulate occurrence rates by stellar mass according to Mulders+2015. Otherwise, assume no dependency on stellar mass.

  • transit_mode (bool, optional) – If True, only transiting planets are simulated. Occurrence rates are modified to reflect the R_*/a transit probability.

  • optimistic (bool, optional) – If True, extrapolate the results of Mulders+2015 by assuming rocky planets are much more common around late-type M dwarfs. If False, assume that occurrence rates plateau with stellar mass for stars cooler than ~M3.

  • optimistic_factor (float, optional) – If optimistic = True, defines how many times more common rocky planets are around late-type M dwarfs compared to Sun-like stars.

  • seed (int or 1-d array_like, optional) – Seed for numpy’s RandomState. Must be convertible to 32 bit unsigned integers.

Returns:

d – Table containing the sample of simulated planets. Replaces the input Table.

Return type:

Table

bioverse.functions.create_planet_per_star(d, R_min=0.5, R_max=14.3)

Generates a single planet for each star with a radius drawn from a uniform distribution between R_min and R_max

Parameters:

  • d (Table) – Table containing simulated host stars.

  • R_min (float, optional) – Minimum planet radius, in Earth units.

  • R_max (float, optional) – Maximum planet radius, in Earth units.

Returns:

d – Table containing the sample of simulated planets. Replaces the input Table.

Return type:

Table

bioverse.functions.name_planets(d)

Assign a name to each star and each planet based on its order in the system.

Parameters:

d (Table) – Table containing the sample of simulated planets.

Returns:

d – Table containing the sample of simulated planets.

Return type:

Table

bioverse.functions.assign_orbital_elements(d, transit_mode=False, seed=42)

Draws values for any remaining Keplerian orbital elements. Eccentricities are drawn from a beta distribution following Kipping et al. (2013).

Parameters:

  • d (Table) – Table containing the sample of simulated planets.

  • transit_mode (bool, optional) – If True, only transiting planets are simulated, so cos(i) < R_*/a for all planets.

  • seed (int or 1-d array_like, optional) – Seed for numpy’s RandomState. Must be convertible to 32 bit unsigned integers.

Returns:

d – Table containing the sample of simulated planets.

Return type:

Table

bioverse.functions.impact_parameter(d, transit_mode=False)

Calculates the impact parameter/transit duration.

Parameters:

  • d (Table) – Table containing the sample of simulated planets.

  • transit_mode (bool, optional) – If True, only transiting planets are simulated, so planets with b > 1 are discarded.

Returns:

d – Table containing the sample of simulated planets.

Return type:

Table

bioverse.functions.assign_mass(d, mr_relation='Wolfgang2016')

Determines planet masses using a probabilistic mass-radius relationship, following Wolfgang et al. (2016). Also calculates density and surface gravity.

Parameters:

  • d (Table) – Table containing the sample of simulated planets.

  • mr_relation (str, optional) – Mass-radius relationship to consider. Must be either ‘Wolfgang2016’ (Wolfgang et al., 2016) or ‘Zeng2016’ (Zeng et al., 2016).

Returns:

d – Table containing the sample of simulated planets.

Return type:

Table

bioverse.functions.classify_planets(d)

Classifies planets by size and instellation following Kopparapu et al. (2018).

Parameters:

d (Table) – Table containing the sample of simulated planets.

Returns:

d – Table containing the sample of simulated planets.

Return type:

Table

bioverse.functions.compute_habitable_zone_boundaries(d)

Computes the habitable zone boundaries from Kopparapu et al. (2014), including dependence on planet mass.

Parameters:

d (Table) – Table containing the sample of simulated planets.

Returns:

d – Table containing the sample of simulated planets.

Return type:

Table

bioverse.functions.scale_height(d)

Computes the equilibrium temperature and isothermal scale height by assigning a mean molecular weight based on size.

Parameters:

d (Table) – Table containing the sample of simulated planets.

Returns:

d – Table containing the sample of simulated planets.

Return type:

Table

bioverse.functions.geometric_albedo(d, A_g_min=0.1, A_g_max=0.7, seed=42)

Assigns each planet a random geometric albedo from 0.1 – 0.7, and computes the contrast ratio when viewed at quadrature.

Parameters:

  • d (Table) – Table containing the sample of simulated planets.

  • A_g_min (float, optional) – Minimum geometric albedo.

  • A_g_max (float, optional) – Maximum geometric albedo.

  • seed (int or 1-d array_like, optional) – Seed for numpy’s RandomState. Must be convertible to 32 bit unsigned integers.

Returns:

d – Table containing the sample of simulated planets.

Return type:

Table

bioverse.functions.effective_values(d)

Computes the “effective” radius and semi-major axis (i.e. assuming an Earth-like planet).

Parameters:

d (Table) – Table containing the sample of simulated planets.

Returns:

d – Table containing the sample of simulated planets.

Return type:

Table

bioverse.functions.compute_transit_params(d)

Computes the transit depth of each planet.

Parameters:

d (Table) – Table containing the sample of simulated planets.

Returns:

d – Table containing the sample of simulated planets.

Return type:

Table

bioverse.functions.apply_bias(d, M_min=0.0, M_max=inf, S_min=0.0, S_max=inf, depth_min=0.0)

Apply detection biases and custom selections to the sample to generate.

Parameters:

  • d (Table) – Table containing the sample of simulated planets.

  • M_min (float) – Minimum planet mass in Mearth

  • M_max (float) – Maximum planet mass in Mearth

  • S_min (float) – Minimum absolute instellation in W/m2

  • S_max (float) – Maximum absolute instellation in W/m2

  • depth_min (float) – Minimum transit depth

Returns:

d – Table containing the new sample after applying the cuts.

Return type:

Table

bioverse.functions.Example1_water(d, f_water_habitable=0.75, f_water_nonhabitable=0.1, minimum_size=True, seed=42)

Determines which planets have water, according to the following model:

f(S,R) = f_water_habitable if S_inner < S < S_outer and 0.8 S^0.25 < R < 1.4

= f_water_nonhabitable if R > 0.8 S^0.25

Parameters:

  • d (Table) – Table containing the sample of simulated planets.

  • f_water_habitable (float, optional) – Fraction of potentially habitable planets (“exo-Earth candidates”) with atmospheric water vapor.

  • f_water_nonhabitable (float, optional) – Fraction of non-habitable planets with atmospheric water vapor.

  • minimum_size (bool, optional) – Whether or not to enforce a minimum size for non-habitable planets to have H2O atmospheres.

  • seed (int or 1-d array_like, optional) – Seed for numpy’s RandomState. Must be convertible to 32 bit unsigned integers.

Returns:

d – Table containing the sample of simulated planets.

Return type:

Table

bioverse.functions.Example2_oxygen(d, f_life=0.7, t_half=2.3, seed=42)

Applies the age-oxygen correlation from Example 2.

Parameters:

  • d (Table) – Table containing the sample of simulated planets.

  • f_life (float, optional) – Fraction of EECs (Earth-sized planets in the habitable zone) with life.

  • tau (float, optional) – Timescale of atmospheric oxygenation (in Gyr), i.e. the age by which 63% of inhabited planets have oxygen.

  • seed (int or 1-d array_like, optional) – Seed for numpy’s RandomState. Must be convertible to 32 bit unsigned integers.

Returns:

d – Table containing the sample of simulated planets.

Return type:

Table

bioverse.functions.magma_ocean(d, wrr=0.005, S_thresh=280.0, simplified=False, diff_frac=0.54, f_rgh=1.0, gh_increase=True, water_incorp=True)

Assign a fraction of planets global magma oceans that change the planet’s radius.

Parameters:

dTable

The population of planets.

wrrfloat, optional

water-to-rock ratio for Turbet+2020 model. Defines the amount of radius increase due to a steam atmosphere. Possible values: [0, 0.0001, 0.001 , 0.005 , 0.01 , 0.02 , 0.03 , 0.04 , 0.05 ] (default: 0.01 = 1% water) If wrr=0, the pure rock MR relation of Zeng+2016 is applied.

S_threshfloat, optional

threshold instellation for runaway greenhouse phase (in W/m2)

simplifiedbool, optional

increase the radii of all runaway greenhouse planets by the same fraction

diff_fracfloat, optional

fractional radius change in the simplified case. E.g., diff_frac = -0.10 is a 10% decrease.

f_rghfloat, optional

fraction of planets within the runaway gh regime that have a runaway gh climate

gh_increasebool, optional

wether or not to consider radius increase due to runaway greenhouse effect (Turbet+2020)

water_incorpbool, optional

wether or not to consider water incorporation in the melt of global magma oceans (Dorn & Lichtenberg 2021)

returns:

d – Table containing the sample of simulated planets with new columns ‘has_magmaocean’.

rtype:

Table