Detailed API

Here, we provide detailed documentation for all of the functions in SysSimPyMMEN.

generate_planet_mass_from_radius_Ning2018_table(R)

Draw a planet mass from the Ning et al. (2018) mass-radius model interpolated on a precomputed table.

Parameters:: R (float) – The planet radius (Earth radii).
Return type:: The planet mass (Earth masses).

Note

Requires a globally defined interpolation object, logMR_table_interp (defined in the same module).

σ_logM_linear_given_radius(R, σ_logM_r1=0.04, σ_logM_r2=0.3, r1=0.5, r2=1.472)

Compute the standard deviation in log planet mass at a given planet radius based on a linear relation.

Parameters:

R (float) – The planet radius (Earth radii).
σ_logM_r1 (float, default=σ_logM_at_radius_min) – The standard deviation in log(mass) (Earth masses) at radius r1.
σ_logM_r2 (float, default=σ_logM_at_radius_switch) – The standard deviation in log(mass) (Earth masses) at radius r2.
r1 (float, default=0.5) – The planet radius (Earth radii) corresponding to σ_logM_r1.
r2 (float, default=radius_switch) – The planet radius (Earth radii) corresponding to σ_logM_r2.

Return type:

The standard deviation in log(mass) (Earth masses) at the given radius.

generate_planet_mass_from_radius_lognormal_mass_around_earthlike_rocky(R, ρ_min=1.0, ρ_max=100.0)

Draw a planet mass from a lognormal distribution centered around the Earth-like rocky model from Li Zeng (https://www.cfa.harvard.edu/~lzeng/tables/massradiusEarthlikeRocky.txt).

Parameters:

R (float) – The planet radius (Earth radii).
ρ_min (float, default=1.) – The minimum planet density (g/cm^3) allowed.
ρ_max (float, default=100.) – The maximum planet density (g/cm^3) allowed.

Return type:

The planet mass (Earth masses).

Note

Requires a globally defined interpolation object, M_earthlike_rocky_interp (defined in the same module).

generate_planet_mass_from_radius_Ning2018_table_above_lognormal_mass_earthlike_rocky_below(R, R_switch=1.472, ρ_min=1.0, ρ_max=100.0)

Draw a planet mass from a combined model (the Ning et al. 2018 model for large radii, and the lognormal distribution centered around the Earth-like rocky model for small radii).

Parameters:

R (float) – The planet radius (Earth radii).
R_switch (float, default=radius_switch) – The transition radius (Earth radii) defining whether to draw from the Ning et al. 2018 model (above this radius) or the lognormal-around Earth-like rocky model (below this radius).
ρ_min (float, default=1.) – The minimum planet density (g/cm^3) allowed.
ρ_max (float, default=100.) – The maximum planet density (g/cm^3) allowed.

Return type:

The planet mass (Earth masses).

generate_planet_mass_from_radius_Ning2018_table_above_lognormal_mass_earthlike_rocky_below_vec(R, R_switch=1.472, ρ_min=1.0, ρ_max=100.0)

Draw a planet mass from a combined model (the Ning et al. 2018 model for large radii, and the lognormal distribution centered around the Earth-like rocky model for small radii).

Parameters:

R (float) – The planet radius (Earth radii).
R_switch (float, default=radius_switch) – The transition radius (Earth radii) defining whether to draw from the Ning et al. 2018 model (above this radius) or the lognormal-around Earth-like rocky model (below this radius).
ρ_min (float, default=1.) – The minimum planet density (g/cm^3) allowed.
ρ_max (float, default=100.) – The maximum planet density (g/cm^3) allowed.

Return type:

The planet mass (Earth masses).

feeding_zone_S2014(M, R, a, Mstar=1.0)

Compute the feeding zone width of a planet using the Schlichting (2014) prescription:

delta_a = 2^(3/2)*a*((a*M)/(R*Mstar))^(1/2).

Parameters:

M (float or array[float]) – The planet mass (Earth masses).
R (float or array[float]) – The planet radius (Earth radii).
a (float or array[float]) – The semi-major axis (AU).
Mstar (float or array[float], default=1.) – The stellar mass (solar masses).

Returns:

delta_a – The feeding zone width (AU) of the planet.

Return type:

float or array[float]

feeding_zone_nHill(M, a, Mstar=1.0, n=10.0)

Compute the feeding zone width of a planet using a number of Hill radii:

delta_a = n*R_Hill = n*a*(M/(3*Mstar))^(1/3).

Parameters:

M (float or array[float]) – The planet mass (Earth masses).
a (float or array[float]) – The semi-major axis (AU).
Mstar (float or array[float], default=1.) – The stellar mass (solar masses).
n (float or array[float], default=10.) – The number of Hill radii to use as the feeding zone.

Returns:

delta_a – The feeding zone width (AU) of the planet.

Return type:

float or array[float]

feeding_zone_RC2014(a_sys)

Compute the feeding zone widths of all the planets in a multi-planet system using the Raymond & Cossou (2014) prescription.

Uses the geometric means of the neighboring planets’ semi-major axes as the boundaries of their feeding zones.

Note

Assumes the same ratio for the inner edge of the innermost planet as its outer edge, and the same ratio for the outer edge of the outermost planet as its inner edge.

Parameters:

a_sys (array[float]) – The semi-major axes (AU) of all the planets.

Returns:

delta_a_sys (array[float]) – The feeding zone widths (AU) of all the planets.
a_bounds_sys (array[float]) – The boundaries (AU) of the feeding zones for the planets (length = n+1 where n is the number of planets). For example, a_bounds_sys[i] and a_bounds_sys[i+1] will be the inner and outer boundaries of the i^th planet.

solid_surface_density(M, a, delta_a)

Compute the solid surface density associated with a planet.

This divides the mass of the planet by the surface area of an annulus of a given width, centered at its semi-major axis.

Parameters:

M (float or array[float]) – The planet mass (Earth masses).
a (float or array[float]) – The semi-major axis (AU).
delta_a (float or array[float]) – The feeding zone width (AU).

Returns:

sigma_solid – The solid surface density (g/cm^2) local to the planet.

Return type:

float or array[float]

solid_surface_density_CL2013(M, a)

Compute the solid surface density of a planet using the Chiang & Laughlin (2013) prescription for the feeding zone width (set equal to the semi-major axis; delta_a = a).

Parameters:

M (float or array[float]) – The planet mass (Earth masses).
a (float or array[float]) – The semi-major axis (AU).

Return type:

The solid surface density (g/cm^2) local to the planet.

solid_surface_density_S2014(M, R, a, Mstar=1.0)

Compute the solid surface density of a planet using the Schlichting (2014) prescription for the feeding zone width (see syssimpymmen.mmen.feeding_zone_S2014()).

Parameters:

M (float or array[float]) – The planet mass (Earth masses).
R (float or array[float]) – The planet radius (Earth radii).
a (float or array[float]) – The semi-major axis (AU).
Mstar (float or array[float], default=1.) – The stellar mass (solar masses).

Return type:

The solid surface density (g/cm^2) local to the planet.

solid_surface_density_nHill(M, a, Mstar=1.0, n=10.0)

Compute the solid surface density of a planet using a number of Hill radii for the feeding zone width (see syssimpymmen.mmen.feeding_zone_nHill()).

Parameters:

M (float or array[float]) – The planet mass (Earth masses).
a (float or array[float]) – The semi-major axis (AU).
Mstar (float or array[float], default=1.) – The stellar mass (solar masses).
n (float or array[float], default=10.) – The number of Hill radii to use as the feeding zone.

Return type:

The solid surface density (g/cm^2) local to the planet.

solid_surface_density_system_RC2014(M_sys, a_sys)

Compute the solid surface densities of all planets in a multi-planet system using the Raymond & Cossou (2014) prescription for their feeding zone widths (see syssimpymmen.mmen.feeding_zone_RC2014()).

Parameters:

M_sys (array[float]) – The planet masses (Earth masses).
a_sys (array[float]) – The semi-major axes (AU) of the planets.

Return type:

The solid surface densities (g/cm^2) local to the planets.

solid_surface_density_prescription(M, R, a, Mstar=1.0, n=10.0, prescription='CL2013')

Compute the solid surface density of a planet or planetary system using a given prescription for the feeding zone width.

Wrapper function that calls the appropriate function based on the prescription string.

Parameters:

M (float or array[float]) – The planet masses (Earth masses).
R (float or array[float]) – The planet radii (Earth radii). Only used for the ‘S2014’ prescription.
a (float or array[float]) – The semi-major axes (AU) of the planets.
Mstar (float or array[float], default=1.) – The stellar mass or masses (solar masses). Only used for the ‘S2014’ or ‘nHill’ prescriptions.
n (float, default=10.) – The number of Hill radii to use as the feeding zone. Only used for the ‘nHill’ prescription.
prescription ({'CL2013', 'S2014', 'nHill', 'RC2014'}, default='CL2013') – The string indicating the prescription to use for computing the feeding zone widths.

Return type:

The solid surface densities (g/cm^2) local to the planets.

Note

If the prescription is ‘RC2014’, the input arrays (i.e. M and a) must all correspond to planets in the same system!

solid_surface_density_CL2013_given_physical_catalog(sssp_per_sys, max_core_mass=10.0)

Compute the solid surface densities for all planets in a physical catalog, using the Chiang & Laughlin (2013) prescription for the feeding zone widths.

Parameters:

sssp_per_sys (dict) – The dictionary containing the planetary and stellar properties for each system in a physical catalog (2-d and 1-d arrays).
max_core_mass (float, default=10.) – The maximum allowed (solid) core mass (Earth masses).

Returns:

sigma_all (array[float]) – The solid surface densities (g/cm^2) of all the planets.
a_all (array[float]) – The semi-major axes (AU) of all the planets.

solid_surface_density_S2014_given_physical_catalog(sssp_per_sys, sssp, max_core_mass=10.0)

Compute the solid surface densities for all planets in a physical catalog, using the Schlichting (2014) prescription for the feeding zone widths.

Parameters:

sssp_per_sys (dict) – The dictionary containing the planetary and stellar properties for each system in a physical catalog (2-d and 1-d arrays).
sssp (dict) – The dictionary containing the planetary and stellar properties of all planets in a physical catalog (1-d arrays).
max_core_mass (float, default=10.) – The maximum allowed (solid) core mass (Earth masses).

Returns:

sigma_all (array[float]) – The solid surface densities (g/cm^2) of all the planets.
a_all (array[float]) – The semi-major axes (AU) of all the planets.

solid_surface_density_nHill_given_physical_catalog(sssp_per_sys, sssp, max_core_mass=10.0, n=10.0)

Compute the solid surface densities for all planets in a physical catalog, using a number of Hill radii for the feeding zone widths.

Parameters:

sssp_per_sys (dict) – The dictionary containing the planetary and stellar properties for each system in a physical catalog (2-d and 1-d arrays).
sssp (dict) – The dictionary containing the planetary and stellar properties of all planets in a physical catalog (1-d arrays).
max_core_mass (float, default=10.) – The maximum allowed (solid) core mass (Earth masses).
n (float, default=10.) – The number of Hill radii to use as the feeding zone.

Returns:

sigma_all (array[float]) – The solid surface densities (g/cm^2) of all the planets.
a_all (array[float]) – The semi-major axes (AU) of all the planets.

solid_surface_density_RC2014_given_physical_catalog(sssp_per_sys, max_core_mass=10.0)

Compute the solid surface densities for all planets in multi-planet systems in a physical catalog, using the Raymond & Cossou (2014) prescription for the feeding zone widths.

Parameters:

sssp_per_sys (dict) – The dictionary containing the planetary and stellar properties for each system in a physical catalog (2-d and 1-d arrays).
max_core_mass (float, default=10.) – The maximum allowed (solid) core mass (Earth masses).

Returns:

sigma_all_2p (array[float]) – The solid surface densities (g/cm^2) of the planets in multi-planet systems.
a_all_2p (array[float]) – The semi-major axes (AU) of the planets in multi-planet systems.
mult_all_2p (array[float]) – The multiplicities of the multi-planet systems each planet belongs to.

solid_surface_density_CL2013_given_observed_catalog(sss_per_sys, max_core_mass=10.0)

Compute the solid surface densities for all planets in an observed catalog, using the Chiang & Laughlin (2013) prescription for the feeding zone widths.

Parameters:

sss_per_sys (dict) – The dictionary containing the planetary and stellar properties for each system in a physical catalog (2-d and 1-d arrays).
max_core_mass (float, default=10.) – The maximum allowed (solid) core mass (Earth masses).

Returns:

sigma_obs (array[float]) – The solid surface densities (g/cm^2) of all the observed planets.
core_mass_obs (array[float]) – The core masses (Earth masses) of all the observed planets. These are the total masses of the planets computed from their observed radii using a mass-radius relation, capped at max_core_mass.
a_obs (array[float]) – The semi-major axes (AU) of all the observed planets.

solid_surface_density_S2014_given_observed_catalog(sss_per_sys, max_core_mass=10.0)

Compute the solid surface densities for all planets in an observed catalog, using the Schlichting (2014) prescription for the feeding zone widths.

Parameters:

sss_per_sys (dict) – The dictionary containing the planetary and stellar properties for each system in a physical catalog (2-d and 1-d arrays).
max_core_mass (float, default=10.) – The maximum allowed (solid) core mass (Earth masses).

Returns:

sigma_obs (array[float]) – The solid surface densities (g/cm^2) of all the observed planets.
core_mass_obs (array[float]) – The core masses (Earth masses) of all the observed planets. These are the total masses of the planets computed from their observed radii using a mass-radius relation, capped at max_core_mass.
a_obs (array[float]) – The semi-major axes (AU) of all the observed planets.

solid_surface_density_nHill_given_observed_catalog(sss_per_sys, max_core_mass=10.0, n=10.0)

Compute the solid surface densities for all planets in an observed catalog, using a number of Hill radii for the feeding zone widths.

Parameters:

sss_per_sys (dict) – The dictionary containing the planetary and stellar properties for each system in a physical catalog (2-d and 1-d arrays).
max_core_mass (float, default=10.) – The maximum allowed (solid) core mass (Earth masses).
n (float, default=10.) – The number of Hill radii to use as the feeding zone.

Returns:

sigma_obs (array[float]) – The solid surface densities (g/cm^2) of all the observed planets.
core_mass_obs (array[float]) – The core masses (Earth masses) of all the observed planets. These are the total masses of the planets computed from their observed radii using a mass-radius relation, capped at max_core_mass.
a_obs (array[float]) – The semi-major axes (AU) of all the observed planets.

solid_surface_density_RC2014_given_observed_catalog(sss_per_sys, max_core_mass=10.0)

Compute the solid surface densities for all planets in observed multi-planet systems in an observed catalog, using the Raymond & Cossou (2014) prescription for the feeding zone widths.

Parameters:

sss_per_sys (dict) – The dictionary containing the planetary and stellar properties for each system in a physical catalog (2-d and 1-d arrays).
max_core_mass (float, default=10.) – The maximum allowed (solid) core mass (Earth masses).

Returns:

sigma_obs_2p (array[float]) – The solid surface densities (g/cm^2) of the observed planets in multi-planet systems.
core_mass_obs_2p (array[float]) – The core masses (Earth masses) of the observed planets in multi-planet systems. These are the total masses of the planets computed from their observed radii using a mass-radius relation, capped at max_core_mass.
a_obs_2p (array[float]) – The semi-major axes (AU) of the observed planets in multi-planet systems.
mult_obs_2p (array[float]) – The multiplicities of the observed multi-planet systems each planet belongs to.

MMSN(a, F=1.0, Zrel=0.33)

Compute the solid surface density of the minimum mass solar nebula (MMSN) at a given separation, as defined by Eq. 2 in Chiang & Youdin (2010) (https://arxiv.org/pdf/0909.2652.pdf).

Note

The normalization is such that the default values of F=1 and Zrel=0.33 give 1 Earth mass of solids in an annulus centered on Earth’s semi-major axis.

Parameters:

a (float or array[float]) – The semi-major axis (AU).
F (float or array[float], default=1.) – A fudge factor.
Zrel (float or array[float], default=0.33) – The relative enrichment in metallicity.

Returns:

sigma_p – The solid surface density (g/cm^2) of the MMSN at the given separation a.

Return type:

float or array[float]

MMEN_power_law(a, sigma0, beta, a0=1.0)

Evaluate a power-law profile for the solid surface density of the minimum mass extrasolar nebula (MMEN) at a given separation.

Given by sigma(a) = sigma0*(a/a0)^beta, where sigma0 (g/cm^2) is the normalization at semi-major axis a0 (AU), and beta is the power-law index.

Parameters:

a (float or array[float]) – The semi-major axis (AU) at which to evaluate the solid surface density.
sigma0 (float) – The solid surface density normalization (g/cm^2) at separation a0.
beta (float) – The power-law index.
a0 (float, default=1.) – The normalization point for the separation (AU).

Returns:

sigma_a – The solid surface density (g/cm^2) at the given separation a.

Return type:

float or array[float]

fit_power_law_MMEN(a_array, sigma_array, a0=1.0, p0=1.0, p1=-1.5)

Fit a power-law representing the minimum mass extrasolar nebula (MMEN) of a planetary system given the planets’ semi-major axes and solid surface densities.

Parameters:

a_array (array[float]) – The semi-major axes (AU) of the planets.
sigma_array (array[float]) – The solid surface densities (g/cm^2) of the planets.
a0 (float, default=1.) – The normalization point for the separation (AU).
p0 (float, default=1.) – The initial guess for the normalization parameter, ‘log(sigma0)’.
p1 (float, default=-1.5) – The initial guess for the power-law index parameter, ‘beta’.

Returns:

sigma0 (float) – The best-fit value for the solid surface density normalization (g/cm^2). Unlike the initial guess (p0), this value is unlogged.
beta (float) – The best-fit value for the power-law index.

fit_power_law_and_scale_up_MMEN(a_sys, sigma_sys, a0=1.0, p0=1.0, p1=-1.5)

Call syssimpymmen.mmen.fit_power_law_MMEN(), and then scale up the resulting power-law fit to be at/above all of the input solid surface densities given by sigma_sys.

Note

Should only be used for fitting MMEN to individual planetary systems; should NOT be used for fitting MMEN to an entire catalog or a collection of planets from different planetary systems.

Parameters:

a_sys (array[float]) – The semi-major axes (AU) of the planets in the system.
sigma_sys (array[float]) – The solid surface densities (g/cm^2) of the planets in the system.
a0 (float, default=1.) – The normalization point for the separation (AU).
p0 (float, default=1.) – The initial guess for the normalization parameter, ‘log(sigma0)’.
p1 (float, default=-1.5) – The initial guess for the power-law index parameter, ‘beta’.

Returns:

sigma0 (float) – The best-fit value for the solid surface density normalization (g/cm^2), multiplied by a scale factor scale_factor. Unlike the initial guess (p0), this value is unlogged.
beta (float) – The best-fit value for the power-law index.
scale_factor (float) – The scale factor required to shift the power-law to be at/above all of the values in sigma_sys. This is always unity for systems with two planets, and greater than or equal to one in general.

fit_power_law_MMEN_all_planets_observed(sss_per_sys, max_core_mass=10.0, prescription='CL2013', n=10.0, a0=1.0, p0=1.0, p1=-1.5)

Compute the solid surface densities and fit a power-law to them for all planets in an observed catalog.

Parameters:

sss_per_sys (dict) – The dictionary containing the planetary and stellar properties for each system in a physical catalog (2-d and 1-d arrays).
max_core_mass (float, default=10.) – The maximum allowed (solid) core mass (Earth masses).
prescription ({'CL2013', 'S2014', 'nHill', 'RC2014'}, default='CL2013') – The string indicating the prescription to use for computing the feeding zone widths.
n (float, default=10.) – The number of Hill radii to use for the feeding zones. Only used for the ‘nHill’ prescription.
a0 (float, default=1.) – The normalization point for the separation (AU).
p0 (float, default=1.) – The initial guess for the normalization parameter, ‘log(sigma0)’.
p1 (float, default=-1.5) – The initial guess for the power-law index parameter, ‘beta’.

Returns:

outputs_dict – A dictionary containing the solid surface densities, power-law fit parameters, and other properties computed from the observed catalog.

Return type:

dict

The output dictionary contains the following fields:

sigma_obs: The solid surface densities (g/cm^2) of all the observed planets (1-d array).
core_mass_obs: The solid core masses (Earth masses) of all the observed planets (1-d array). These are the total masses of the planets computed from their observed radii using a mass-radius relation, capped at max_core_mass.
a_obs: The semi-major axes (AU) of all the observed planets (1-d array).
sigma0: The best-fit value for the solid surface density normalization (g/cm^2).
beta: The best-fit value for the power-law index.

fit_power_law_MMEN_all_planets_physical(sssp_per_sys, sssp, max_core_mass=10.0, prescription='CL2013', n=10.0, a0=1.0, p0=1.0, p1=-1.5)

Compute the solid surface densities and fit a power-law to them for all planets in a physical catalog.

Parameters:

sssp_per_sys (dict) – The dictionary containing the planetary and stellar properties for each system in a physical catalog (2-d and 1-d arrays).
sssp (dict) – The dictionary containing the planetary and stellar properties of all planets in a physical catalog (1-d arrays).
max_core_mass (float, default=10.) – The maximum allowed (solid) core mass (Earth masses).
prescription ({'CL2013', 'S2014', 'nHill', 'RC2014'}, default='CL2013') – The string indicating the prescription to use for computing the feeding zone widths.
n (float, default=10.) – The number of Hill radii to use for the feeding zones. Only used for the ‘nHill’ prescription.
a0 (float, default=1.) – The normalization point for the separation (AU).
p0 (float, default=1.) – The initial guess for the normalization parameter, ‘log(sigma0)’.
p1 (float, default=-1.5) – The initial guess for the power-law index parameter, ‘beta’.

Returns:

outputs_dict – A dictionary containing the solid surface densities, power-law fit parameters, and other properties computed from the observed catalog.

Return type:

dict

The output dictionary contains the following fields:

sigma_all: The solid surface densities (g/cm^2) of all the planets (1-d array).
a_all: The semi-major axes (AU) of all the planets (1-d array).
sigma0: The best-fit value for the solid surface density normalization (g/cm^2).
beta: The best-fit value for the power-law index.

fit_power_law_MMEN_per_system_observed(sss_per_sys, n_mult_min=2, max_core_mass=10.0, prescription='CL2013', n=10.0, a0=1.0, p0=1.0, p1=-1.5, scale_up=False)

Fit power-laws to the solid surface densities of the planets in each multi-planet system in an observed catalog.

Parameters:

sss_per_sys (dict) – The dictionary containing the planetary and stellar properties for each system in a physical catalog (2-d and 1-d arrays).
n_mult_min (int, default=2) – The minimum multiplicity to include.
max_core_mass (float, default=10.) – The maximum allowed (solid) core mass (Earth masses).
prescription ({'CL2013', 'S2014', 'nHill', 'RC2014'}, default='CL2013') – The string indicating the prescription to use for computing the feeding zone widths.
n (float, default=10.) – The number of Hill radii to use for the feeding zones. Only used for the ‘nHill’ prescription.
a0 (float, default=1.) – The normalization point for the separation (AU).
p0 (float, default=1.) – The initial guess for the normalization parameter, ‘log(sigma0)’.
p1 (float, default=-1.5) – The initial guess for the power-law index parameter, ‘beta’.
scale_up (bool, default=False) – Whether to scale up the normalization such that the power-law fit for each system is at/above the solid surface densities of every planet in the system.

Returns:

fit_per_sys_dict – A dictionary containing the power-law fit parameters and other properties for each included system in the observed catalog.

Return type:

dict

The output dictionary contains the following fields:

m_obs: The observed multiplicities of the included systems (greater than or equal to n_mult_min; 1-d array).
Mstar_obs: The stellar masses of the included system (1-d array).
sigma0: The best-fit values for the solid surface density normalizations (g/cm^2) of the included systems (1-d array). If scale_factor=True, these normalization values have already been multiplied by the scale factor of each system.
scale_factor: The scale factors required to increase the normalizations of each system such that the power-law fits are at/above the solid surface densities of every planet in the system (1-d array).
beta: The best-fit values for the power-law indices of the included systems (1-d array).

fit_power_law_MMEN_per_system_physical(sssp_per_sys, sssp, n_mult_min=2, max_core_mass=10.0, prescription='CL2013', n=10.0, a0=1.0, p0=1.0, p1=-1.5, scale_up=False, N_sys=10000)

Fit power-laws to the solid surface densities of the planets in each multi-planet system in a physical catalog.

Parameters:

sssp_per_sys (dict) – The dictionary containing the planetary and stellar properties for each system in a physical catalog (2-d and 1-d arrays).
sssp (dict) – The dictionary containing the planetary and stellar properties of all planets in a physical catalog (1-d arrays).
n_mult_min (int, default=2) – The minimum multiplicity to include.
max_core_mass (float, default=10.) – The maximum allowed (solid) core mass (Earth masses).
prescription ({'CL2013', 'S2014', 'nHill', 'RC2014'}, default='CL2013') – The string indicating the prescription to use for computing the feeding zone widths.
n (float, default=10.) – The number of Hill radii to use for the feeding zones. Only used for the ‘nHill’ prescription.
a0 (float, default=1.) – The normalization point for the separation (AU).
p0 (float, default=1.) – The initial guess for the normalization parameter, ‘log(sigma0)’.
p1 (float, default=-1.5) – The initial guess for the power-law index parameter, ‘beta’.
scale_up (bool, default=False) – Whether to scale up the normalization such that the power-law fit for each system is at/above the solid surface densities of every planet in the system.
N_sys (int, default=10000) – The maximum number of systems to be included (to save time if there are too many systems in the physical catalog).

Returns:

fit_per_sys_dict – A dictionary containing the power-law fit parameters and other properties for each included system in the physical catalog.

Return type:

dict

The output dictionary contains the following fields:

n_pl: The multiplicities of the included systems (greater than or equal to n_mult_min; 1-d array).
sigma0: The best-fit values for the solid surface density normalizations (g/cm^2) of the included systems (1-d array). If scale_factor=True, these normalization values have already been multiplied by the scale factor of each system.
scale_factor: The scale factors required to increase the normalizations of each system such that the power-law fits are at/above the solid surface densities of every planet in the system (1-d array).
beta: The best-fit values for the power-law indices of the included systems (1-d array).

fit_power_law_MMEN_per_system_observed_and_physical(sssp_per_sys, sssp, n_mult_min=2, max_core_mass=10.0, prescription='CL2013', n=10.0, a0=1.0, p0=1.0, p1=-1.5, scale_up=False)

Fit power-laws to the solid surface densities of the observed and physical planets in each multi-planet system in a physical catalog.

Computes the solid surface densities and fit a power-law to each multi-planet system in the physical catalog, for the observed planets only and then for all the planets in those systems (using the physical planet properties for both).

Parameters:

sssp_per_sys (dict) – The dictionary containing the planetary and stellar properties for each system in a physical catalog (2-d and 1-d arrays).
sssp (dict) – The dictionary containing the planetary and stellar properties of all planets in a physical catalog (1-d arrays).
n_mult_min (int, default=2) – The minimum multiplicity to include.
max_core_mass (float, default=10.) – The maximum allowed (solid) core mass (Earth masses).
prescription ({'CL2013', 'S2014', 'nHill', 'RC2014'}, default='CL2013') – The string indicating the prescription to use for computing the feeding zone widths.
n (float, default=10.) – The number of Hill radii to use for the feeding zones. Only used for the ‘nHill’ prescription.
a0 (float, default=1.) – The normalization point for the separation (AU).
p0 (float, default=1.) – The initial guess for the normalization parameter, ‘log(sigma0)’.
p1 (float, default=-1.5) – The initial guess for the power-law index parameter, ‘beta’.
scale_up (bool, default=False) – Whether to scale up the normalization such that the power-law fit for each system is at/above the solid surface densities of every planet in the system.

Returns:

fit_per_sys_dict – A dictionary containing the power-law fit parameters and other properties for each multi-planet system in the observed catalog.

Return type:

dict

The output dictionary contains the following fields:

n_pl_true: The true multiplicities of the included systems (greater than or equal to n_mult_min) (1-d array).
n_pl_obs: The observed multiplicities of the included systems (1-d array).
Mp_tot_true: The total solid core mass (Earth masses) of all the planets in each included system (1-d array).
Mp_tot_obs: The total solid core mass (Earth masses) of only the observed planets in each included system (1-d array).
sigma0_true: The best-fit values for the solid surface density normalizations (g/cm^2) from fitting all the planets of the included systems (1-d array). If scale_factor=True, these normalization values have already been multiplied by the scale factor of each system.
sigma0_obs: The best-fit values for the solid surface density normalizations (g/cm^2) from fitting only the observed planets of the included systems (1-d array). If scale_factor=True, these normalization values have already been multiplied by the scale factor of each system.
scale_factor_true: The scale factors required to increase the normalizations of each system such that the power-law fits are at/above the solid surface densities of every planet in the system (1-d array).
scale_factor_obs: The scale factors required to increase the normalizations of each system such that the power-law fits are at/above the solid surface densities of every observed planet in the system (1-d array).
beta_true: The best-fit values for the power-law indices from fitting all the planets of the included systems (1-d array).
beta_obs: The best-fit values for the power-law indices from fitting only the observed planets of the included systems (1-d array).

plot_feeding_zones_and_power_law_fit_MMEN_per_system_observed_and_physical(sssp_per_sys, sssp, n_mult_min=2, n_mult_max=10, max_core_mass=10.0, prescription='CL2013', n=10.0, a0=1.0, p0=1.0, p1=-1.5, scale_up=False, N_sys=10)

Make plots of solid surface density versus semi-major axis, including the feeding zones of each planet and a power-law fit to all the physical and observed planets, for each multi-planet system in a physical catalog.

Parameters:

sssp_per_sys (dict) – The dictionary containing the planetary and stellar properties for each system in a physical catalog (2-d and 1-d arrays).
sssp (dict) – The dictionary containing the planetary and stellar properties of all planets in a physical catalog (1-d arrays).
n_mult_min (int, default=2) – The minimum multiplicity to include.
n_mult_max (int, default=10) – The maximum multiplicity to include.
max_core_mass (float, default=10.) – The maximum allowed (solid) core mass (Earth masses).
prescription ({'CL2013', 'S2014', 'nHill', 'RC2014'}, default='CL2013') – The string indicating the prescription to use for computing the feeding zone widths.
n (float, default=10.) – The number of Hill radii to use for the feeding zones. Only used for the ‘nHill’ prescription.
a0 (float, default=1.) – The normalization point for the separation (AU).
p0 (float, default=1.) – The initial guess for the normalization parameter, ‘log(sigma0)’.
p1 (float, default=-1.5) – The initial guess for the power-law index parameter, ‘beta’.
scale_up (bool, default=False) – Whether to scale up the normalization such that the power-law fit for each system is at/above the solid surface densities of every planet in the system.
N_sys (int, default=10) – The maximum number of systems to plot. A separate figure will be plotted for each system.

solid_mass_integrated_r0_to_r_given_power_law_profile(r, r0, sigma0, beta, a0=1.0)

Compute the total solid mass from a power-law profile for the solid surface density, within a given separation.

Integrates the power-law over an annular area from radius r0 to r.

Parameters:

r (float) – The separation (AU) of the outer boundary.
r0 (float) – The separation (AU) of the inner boundary.
sigma0 (float) – The normalization for the solid surface density (g/cm^2) at separation a0.
beta (float) – The power-law index.
a0 (float, default=1.) – The normalization point for the separation (AU).

Returns:

M_r – The total integrated solid mass (Earth masses).

Return type:

float

Warning

The inner boundary r0 must be non-zero to avoid infinite mass for beta <= -2.