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. (2015).

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, SpT=None, seed=42, m_G_max=None, M_G_max=None, lum_evo=False, fill_missing=True, ecliptic_coords=True, schema={'L_st': Float64, 'M_G': Float64, 'M_st': Float64, 'RV': Float64, 'R_st': Float64, 'SpT': String, 'T_eff_st': Int64, 'binary': Boolean, 'd': Float64, 'dec': Float64, 'ra': Float64, 'star_name': String, 'subSpT': String}, xyz=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.

• SpT (list of str, optional) – List of spectral types to include in the sample. Example: SpT=[‘F’, ‘G’, ‘K’, ‘M’].

• 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 apparent G magnitude of stars

• M_G_max (float, optional) – Maximum absolute 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. 2015.

• fill_missing (bool, optional) – Fill in missing values of stellar properties.

• ecliptic_coords (bool, optional) – compute ecliptic coordinates for stars

• schema (polars schema object, optional) – schema for column datatypes used for polars file reading

• xyz (bool, optional) – compute galactic xyz coordinates

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 DR3. 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.

For high mass stars, this function reads a saved catalog of stars from Gaia DR3. The default stellar catalog extends to 150 pc, and contains stars with Teff > 4000 K. To generate a new stellar catalog, use the update_stellar_catalog function in util.py to query the Gaia archive.

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='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.read_HPIC(d, filename='HPIC.txt', Vmag_max=None, d_max=None, required_props=['d', 'logL', 'Vmag'])

Generates stars from the HPIC the HWO Preliminary input catalog of Tuchow+, 2024

Parameters:

• d (Table) – Empty table object

• filename (str, optional) – Name of the file containing the HPIC

• Vmag_max (float, optional) – Max V magnitude for simulated stars

• d_max (float, optional) – Max distance in pc for simulated stars. Note the HPIC was constructed with a max dist of 50 pc

• required_props (list of str, optional) – Required stellar properties for generated stars. Stars without these properties will be omitted from the target list. Use names from bioverse not standard HPIC names of properties.

Returns:

d – Table object with generated 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. Planets are only assigned to stars with masses between 0.01 and 1.629 solar masses.

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.solve_kep(d, t=0, M=None, n_it=3, at_quadrature=False)

Solves Kepler equation for generated planets, calculating true anomalies, true planet star separations, phase angles, and angular separations in milliarcsecs. Adapted from the get_xyz function in util.py. If computing contrast with at_quadrature=False, add this step beforehand :param d: Table containing the sample of simulated planets. :type d: Table :param t: Time at which to solve Kepler equation. Same units as period. The default is 0. :type t: float, optional :param M: Mean longitude. If not specified, calculated at time t. The default is None. :type M: float, optional :param n_it: Number of iterations for the Newton method of solving the Kepler equation.

The default is 3.

Parameters:

at_quadrature (bool,optional) – Are planets assumed to be observed at quadrature phase? Default is False

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

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.compute_contrast(d, at_quadrature=True, phasefunc=<function lambertian_phase>)

Function to compute planet-star contrast. If not at quadrature, requires phase angle calculated by solve_kep function

Parameters:

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

• at_quadrature (Boolean, optional) – Specify whether observations are taken at quadrature phase The default is True.

• phasefunc (function, optional) – User defined phase function. Not called in quadrature case. The default is the Lambertian phase function.

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