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, a_min=0.0, a_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=False, 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=False, generate_RV=False)¶

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

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.
a_min (float, optional) – Minimum stellar age, in Gyr.
a_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.
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
generate_RV (bool, optional) – drawn random radial velocities for simulated stars

Returns:

d – Table containing the sample of real stars.

Return type:

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, cat_file='/home/docs/checkouts/readthedocs.org/user_builds/bioverse/envs/latest/lib/python3.11/site-packages/bioverse/Data/Gaia.csv', catalog=None)¶

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.

For most efficient performance provide catalog as an argument so that the Gaia catalog doesn’t need to be reopened every time this function is called.

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.
cat_file (str, optional) – file name for gaia catalog
catalog (numpy.ndarray, optional) – Gaia catalog saved to local memory. Loading the catalog via the util.read_catalog function will yield the best performance

Returns:

d – Table containing the sample of simulated stars.

Return type:

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:

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:

bioverse.functions.schedule_DI_survey(d, survey=None, Ag=0.3, R_eec=1.0, SNR=7, band='Vmag', **e_kwargs)¶

Function to generate a survey schedule for a direct imaging mission. Currently this uses a simple prioritization scheme based on the time it would take to observe an Earth analog. Call this function before planet generation.

Parameters:

Ag (float, optional) – default value for geometric albedo. Not used if albedo is already defined
R_eec (float, optional) – The radius of an Earth analog in R_earth. The default is 1.0.
SNR (float, optional) – Required signal to noise for Earth-like planet characterization
band (str, optional) – name of photometric band used in exposure time calculator
**e_kwargs – keyword arguments for exposure time calculator

Returns:

d – Table of stars to be surveyed

Return type:

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:

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:

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:

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, zero_ecc=False, e_max=0.8, seed=42)¶

Draws values for any remaining Keplerian orbital elements. Eccentricities either set to zero or 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.
zero_ecc (bool, optional) – Set all eccentricities to zero.
e_max (float, optional) – Maximum eccentricity value to be assigned
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:

bioverse.functions.compute_transit_params(d, transit_mode=False, ecc_correction=True)¶

Computes the transit depth, impact parameter, and transit duration of each planet.

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.
ecc_correction (bool, optional) – If True use adjusted equation for transit duration, using equations (14) and (16) from Winn (2010)

Returns:

d – Table containing the sample of simulated planets.

Return type:

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

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).
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:

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, HZ_formulation='K14')¶

Computes the habitable zone boundaries for a given formulation.

Parameters:

d (Table) – Table containing the sample of simulated planets.
HZ_formulation (str, optional) – Formulation of the habitable zone to use. Options are: ‘K14’ : Kopparapu et al. (2014) HZ, including dependence on planet mass ‘K13’: Kopparapu el al. (2013) HZ, conservative (moist greenhouse,max_greenhouse) ‘K13_optimistic’: Kopparapu+ 2013 HZ, optimistic base on recent Venus and early Mars ‘R18’: Ramirez et al. (2018) HZ, including methane

Returns:

d – Table containing the sample of simulated planets.

Return type:

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:

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:

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

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:

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:

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