Package resokit.utils

The ResoKit.utils package includes tools for data analysis.

resokit.utils.calc_a(period: float, m_star: float, m_planet: float) → float

Calculate the semi-major axis of a planet.

Equation:

\(a = \left(\dfrac{G (m_\star + m_p)}{4 \pi^2 P^2}\right)^{1/3}\)

Parameters:

• period (float) – Orbital period of the planet, in days.

• m_star (float) – Mass of the star, in solar masses.

• m_planet (float) – Mass of the planet, in Jupiter masses.

Returns:

Semi-major axis of the planet, in AU.

Return type:

float

resokit.utils.calc_hill_radius(a: float, e: float, m_star: float, m_planet: float) → float

Calculate the Hill radius of a planet.

Equation:

\(r_H = a (1 - e) \left(\dfrac{m_p} {3 (m_\star + m_p)}\right)^{1/3}\)

Parameters:

• a (float) – Semi-major axis of the planet, in AU.

• e (float) – Eccentricity of the planet.

• m_star (float) – Mass of the star, in solar masses.

• m_planet (float) – Mass of the planet, in Jupiter masses.

Returns:

Hill radius of the planet, in AU.

Return type:

float

resokit.utils.calc_period(a: float, m_star: float, m_planet) → float

Calculate the orbital period of a planet.

Equation:

\(P = 2 \pi \sqrt{\dfrac{a^3}{G (m_\star + m_p)}}\)

Parameters:

• a (float) – Semi-major axis of the planet, in AU.

• m_star (float) – Mass of the star, in solar masses.

• m_planet (float) – Mass of the planet, in Jupiter masses.

Returns:

Orbital period of the planet, in days.

Return type:

float

resokit.utils.float_to_fraction(value: float, max_iter: int | None = None, max_error: float | None = None, as_fraction: bool = False, stop_func: Callable | None = None, verbose: bool = True) → Fraction | Tuple[int, int]

Calculate the continued fraction approximation of a value.

Parameters:

• value (float) – Value to approximate.

• max_iter (int, optional.) – Maximum number of terms to use in the continued fraction expansion.

• max_error (float, optional.) – Maximum relative error tolerance for the approximation.

• as_fraction (bool, optional. Default: False) – Whether to return the result as a Fraction object.

• stop_func (callable, optional) – Function to use as a stopping criterion for the approximation. Takes the numerator and denominator of the current approximation as arguments and returns a boolean indicating whether to stop. If STOP is reached, the function will return the previous approximation.

• verbose (bool, optional. Default: True) – Whether to print the intermediate results of the calculation.

Returns:

Tuple with the numerator and denominator of the best approximation, or a Fraction object if as_fraction is True.

Return type:

Union[Fraction, Tuple[int, int]]

Package resokit.utils.mass_radius

The ResoKit.utils.mass_radius package includes tools for M-R analysis.

resokit.utils.mass_radius.estimate_radius(mass: float | ndarray, mass_err_min: float | ndarray = 0.0, mass_err_max: float | ndarray = 0.0, model: str = 'ck17', bivariate: float = 0.5, err_method: int = -1, density: float = 0.0, silent: bool = False) → Tuple[float, float, float] | ndarray

Calculate the radius of a planet using the power-law approximation.

The different models available are: Chen & Kipping (2017), Otegi et al. (2020), Edmondson et al. (2023), and Müller et al. (2024).

Equation:

\(radius = C \times mass^S\)

Parameters:

• mass (float, np.ndarray) – Mass of the planet, in Earth masses.

• mass_err_min (float, np.ndarray) – Lower error of the mass, in Earth masses.

• mass_err_max (float, np.ndarray) – Upper error of the mass, in Earth masses.

• model (str, optional. Default: "ck17") – Model to use for the mass-radius power-law relation. ‘ck17’: Chen & Kipping (2017) ‘o20’: Otegi et al. (2020) [density|bivariate] ‘e23’: Edmondson et al. (2023) ‘m24’: Müller et al. (2024)

• bivariate (float, optional. Default: 0.5) – Probability of using the lower branch if the estimation falls in a bivariate region. Must be a number between 0 and 1. Only used if model is ‘o20’.

• err_method (int, optional. Default: -1) – Which method implement for error calculation. Method -1: Do not calculate errors. Return only the radius. Method 0: Do not calculate errors. Return both as 0.0. Method 1: (Naive) Error propagation with the power-law approximation, using the mass error as the maximum of the two extremes. Method 2: Evalaute the mass extremes and calculate each radius extreme. Method 3: Returns the approximate model error as value errors.

• density (float, optional. Default: 0.0) – Density of the planet, in kg m^-3. Only used if model is ‘o20’. If equal to 0.0, the code uses bivariate

• silent (bool, optional. Default: False) – Whether to silence the warning if the radius falls in a bivariate region, or if the estimation is not accurate.

Returns:

result – Estimated radius, and its minimum and maximum errors, in Earth radii. If mass is a scalar, the tuple is (radius, radius_err_min, radius_err_max), else it is a (n,3) numpy array. If err_method=0, the tuple | array is (radius, 0.0, 0.0).

Return type:

tuple[float, float, float] or np.ndarray

References

Chen, J., & Kipping, D. 2017, ApJ, 834, 17

Otegi, J. F., Bouchy, F., & Helled, R. 2020, A&A, 634, A43

Edmondson, K., Norris, J., & Kerins, E. 2023, Open J. Astrophysics, submitted

Müller S., Baron J., Helled R., Bouchy F. & Parc L. 2024, A&A, 686, A296

resokit.utils.mass_radius.estimate_mass(radius: float | ndarray, radius_err_min: float | ndarray = 0.0, radius_err_max: float | ndarray = 0.0, model: str = 'ck17', multivariate: float | tuple | list | None = None, err_method: int = -1, density: float = 0.0, silent: bool = False) → Tuple[float, float, float] | ndarray

Calculate the mass of a planet using a power-law approximation.

The different models available are: Chen & Kipping (2017), Otegi et al. (2020), Edmondson et al. (2023), and Müller et al. (2024).

Equation:

\(mass = \frac{1}{C} \times radius^{1/S}\)

Parameters:

• radius (float, np.ndarray) – Radius of the planet, in Earth radii.

• radius_err_min (float, np.ndarray) – Lower error of the radius, in Earth radii.

• radius_err_max (float, np.ndarray) – Upper error of the radius, in Earth radii.

• model (str, optional. Default: "ck17") – Model to use for the mass-radius power-law relation. ‘ck17’: Chen & Kipping (2017) [trivariate] ‘o20’: Otegi et al. (2020) [density|bivariate] ‘e23’: Edmondson et al. (2023) ‘m24’: Müller et al. (2024) [bivariate]

• multivariate (float, tuple, optional. Default: 0.5) – Probability of using the (first, second, …) branch if the estimation falls in a multivariate region. For bivariate models (‘o20’, ‘m24’), it must be a float between 0 and 1. Default is 0.5. For trivariate model “ck17”, it must be a tuple of two floats between 0 and 1, where the sum of them must be lower equal than 1. Default is (0.1, 0.85).

• err_method (int, optional. Default: -1) – Which method implement for error calculation. Method -1: Do not calculate errors. Return only the mass. Method 0: Do not calculate errors. Return both as 0.0. Method 1: (Naive) Error propagation with the power-law approximation, using the radius error as the maximum of the two extremes. Warning: May return excessively large errors for multivariate sections. Method 2: Evaluate the radius extremes and calculate each mass extreme with the power-law approximation. Method 3: Returns the approximate model error as value errors.

• density (float, optional. Default: 0.0) – Density of the planet, in kg m^-3. Only used if model is ‘o20’. If equal to 0.0, the code uses multivariate float instead, to determine which branch to use.

• silent (bool, optional. Default: False) – Whether to silence the warning if the radius falls in a multivariate region, or if the estimation is not accurate.

Returns:

result – Estimated mass, and its minimum and maximum errors, in Earth masses. If radius is a scalar, the tuple is (mass, mass_err_min, mass_err_max), else it is a (n,3) numpy array. If err_method=0, the tuple | array is (mass, 0.0, 0.0).

Return type:

tuple[float, float, float] or np.ndarray

References

Chen, J., & Kipping, D. 2017, ApJ, 834, 17

Otegi, J. F., Bouchy, F., & Helled, R. 2020, A&A, 634, A43

Edmondson, K., Norris, J., & Kerins, E. 2023, Open J. Astrophysics, submitted

Müller S., Baron J., Helled R., Bouchy F. & Parc L. 2024, A&A, 686, A296

Package resokit.utils.mmr

The ResoKit.utils.mmr package includes diverse tools for MMRs analysis.

resokit.utils.mmr.closest_mmr3b(a: float, b: float, order3: int = 0, max_coeff3: int = 10, max_order3: int = 0, bounds: Tuple[float, float, float, float] | None = None, radius: float = 0.001, verbose: bool = True, **minimize_kwargs) → Tuple[List[int], float]

Find the closest 3-body mean-motion resonance to a point.

Parameters:

• a (float) – The x-coordinate of the point.

• b (float) – The y-coordinate of the point.

• order3 (int, optional. Default: 0) – Exact order for 3P-MMRs.

• max_coeff3 (int, optional. Default: 10) – Calculate 3P-MMRs up to this maximum integer coefficient.

• max_order3 (int, optional. Default: 0) – Calculate 3P-MMRs up to this maximum order. If set to 0, only the exact order is considered.

• bounds (tuple[float, float, float, float], optional. Default: None) – The limits of the region (x_min, x_max, y_min, y_max). If not provided and radius is not None, the function will use the search radius around the point. If

• radius (float, optional. Default: 1e-3) – The radius of the search area around the point. If bounds are provided, the radius will be ignored.

• ret_point (bool, optional. Default: False)

• verbose (bool, optional. Default: True) – Whether to print the optimization results.

• minimize_kwargs (dict, optional) – Additional arguments for the :py:func:scipy.optimize.minimize function.

Returns:

• resonance (list[int, int, int]) – The coefficients of the closest 3-body resonance.

• distance (float) – The distance to the closest 3-body resonance.

resokit.utils.mmr.label_mmr3b(resonance: tuple, ax: Axes | None = None, lims: tuple | None = None, warn: bool = True) → Axes

Annotate a plot with the label of a resonance line.

The label is placed where the resonance line crosses either the right or top axis of the plot. The resonance coefficients are displayed in a compact format. If the line does not cross these axes, a warning is printed.

Parameters:

• resonance (tuple) – Coefficients of the resonance line (a, b, c) in the form a * x + b + c / y = 0.

• ax (matplotlib.axes.Axes, optional. Default: None) – The axis object on which the label will be placed. If not provided, the function will use the current axis.

• lims (tuple, optional. Default: None) – Custom axis limits in the format (x_min, x_max, y_min, y_max). If not provided, the function will use the current axis limits.

• warn (bool, optional. Default: True) – Whether to print a warning if the resonance does not cross the right or top axis.

Returns:

ax – The axis object with the annotations.

Return type:

Matplotlib Axes

resokit.utils.mmr.mindist_mmr3b(a: float, b: float, resonance: Tuple[int, int, int], x0: float | None = None, unphysical: bool = False, **minimize_kwargs) → Tuple[float, float, float]

Calculate the minimum distance to a 3-body resonance curve.

Parameters:

• a (float) – The x-coordinate of the point.

• b (float) – The y-coordinate of the point.

• resonance (Tuple[int, int, int]) – Coefficients defining the resonance.

• x0 (float, optional. Default: None) – Initial guess for the optimization. If None, the function will use the middle point of the curve.

• unphysical (bool, optional. Default: False) – Whether to allow unphysical solutions. (y below 1)

• minimize_kwargs (dict, optional) – Additional arguments for :py:func:scipy.optimize.minimize function.

Returns:

• x_min (float) – The x coordinate of the minimum distance.

• y_min (float) – The y coordinate of the minimum distance.

• distance_min (float) – The minimum distance to the resonance curve.

resokit.utils.mmr.mmr3b(x: float | ndarray, resonance: Tuple[int, int, int]) → float | ndarray

Compute the 3-body mean-motion resonance (MMR) curve.

Equation

\(a * x + b + c / y = 0\)

Parameters:

• x (float or np.ndarray) – The independent variable for the curve.

• resonance (tuple[int, int, int]) – Coefficients (a, b, c) defining the resonance.

Returns:

y – The corresponding values of the 3-body resonance curve. Singularities are replaced with NaN.

Return type:

float or np.ndarray

resokit.utils.mmr.mmrs_in_area(bounds: Tuple[float, float, float, float], order3: int = 0, max_coeff3: int = 10, max_order3: int = 0, mmr2b: bool = True, order2: int = 2, max_coeff2: int = 10, max_order2: int = 2, verbose: bool = False) → list

Identify 3-body and 2-body MMRs in a specified phase-space region.

This function identifies 3-body mean-motion resonances (3P-MMRs) and optionally 2-body mean-motion resonances (2P-MMRs) in a specified region of the phase space.

Parameters:

• bounds (tuple[float, float, float, float]) – The limits of the region (x_min, x_max, y_min, y_max) in the phase space. Remeber that x_min and y_min must be > 1.

• order3 (int, optional. Default: 0) – Exact order for 3P-MMRs.

• max_coeff3 (int, optional. Default: 10) – Calculate 3P-MMRs up to this maximum integer coefficient.

• max_order3 (int, optional. Default: 0) – Calculate 3P-MMRs up to this maximum order. If set to 0, only the exact order is considered.

• mmr2b (bool, optional. Default: True) – Whether to compute 2P-MMRs.

• order2 (int, optional. Default: 2) – Exact order for 2P-MMRs.

• max_coeff2 (int, optional. Default: 10) – Calculate 2P-MMRs up to this maximum integer coefficient.

• max_order2 (int, optional. Default: 2) – Calculate 2P-MMRs up to this maximum order. If set to 0, only the exact order is considered.

• verbose (bool, optional. Default: False) – Whether to print the resonances found.

Returns:

resonances – A list containing detected 3P-MMRs and optionally 2P-MMRs along the x and y axes. This last case is returned as [r3, r2x, r2y], where r3, r2x, and r2y are lists of 3P-MMRs, 2P-MMRs along the x-axis, and 2P-MMRs along the y-axis, respectively.

Return type:

list

resokit.utils.mmr.plot_mmrs(bounds: Tuple[float, float, float, float] | None = None, order3: int = 0, max_coeff3: int = 10, max_order3: int = 0, mmr2b: bool = True, order2: int = 2, max_coeff2: int = 10, max_order2: int = 2, n_points: int = 1000, ax: Axes | None = None, label_mmrs: bool = False, label_2mmrs: bool = False, **plot_kwargs)

Plot 3-body and 2-body mean-motion resonances in a phase-space region.

This function plots 3-body mean-motion resonances (3P-MMRs) and optionally 2-body mean-motion resonances (2P-MMRs) in a specified region of the phase space.

Note

The function will adjust the bounds to the axis limits if the axis object is provided. If the label_mmrs option is used, it is recommended to set the xlim and ylim before calling this function, or the labels may be placed outside the plot.

Parameters:

• bounds (Tuple[float, float, float, float], optional. Default: None) – The limits of the region (x_min, x_max, y_min, y_max). If ax is provided, the bounds will be adjusted to the axis limits.

• order3 (int. Default: 0) – Exact order for 3P-MMRs.

• max_coeff3 (int, optional. Default: 10) – Calculate 3P-MMRs up to this maximum integer coefficient.

• max_order3 (int, optional. Default: 0) – Calculate 3P-MMRs up to this maximum order. If set to 0, only the exact order is considered (default: 10).

• mmr2b (bool, optional. Default: True) – Whether to compute 2P-MMRs.

• order2 (int, optional. Default: 2) – Exact order for 2P-MMRs.

• max_coeff2 (int, optional. Default: 10) – Calculate 2P-MMRs up to this maximum integer coefficient.

• max_order2 (int, optional. Default: 2) – Calculate 2P-MMRs up to this maximum order. If set to 0, only the exact order is considered.

• n_points (int, optional. Default: 500) – Number of points for the curve.

• ax (plt.Axes, optional. Default: None) – The axis object on which the plot will be drawn. If not provided, a new figure and axis will be created.

• label_mmrs (bool, optional. Default: False) – Whether to label the resonances on the plot. Recommended to set xlim and ylim before using this option, or the labels may be placed outside the plot. (default: False).

• label_2mmrs (bool, optional. Default: False) – Whether to label the 2-body resonances on the plot. Recommended to set xlim and ylim before using this option, or the labels may be placed outside the plot. (default: False).

• plot_kwargs (dict, optional) – Additional arguments for the plot function.

Returns:

ax – The axis object on which the plot was drawn.

Return type:

Matplotlib Axes