exoctk.phase_constraint_overlap package

Submodules

exoctk.phase_constraint_overlap.phase_constraint_overlap module

Phase contraint overlap tool. This tool calculates the minimum and maximum phase of the primary or secondary transit (by default, primary) based on parameters provided by the user.

Authors:

Catherine Martlin, 2018 Mees Fix, 2018 Nestor Espinoza, 2020

Usage:

calculate_constraint <target_name> [–t0=<t0>] [–period=<p>] [–pre_duration=<pre_duration>] [–transit_duration=<trans_dur>] [–window_size=<win_size>] [–secondary] [–eccentricity=<ecc>] [–omega=<omega>] [–inclination=<inc>] [–winn_approx] [–get_secondary_time]

Arguments:

<target_name> Name of target

Options:

-h –help Show this screen. –version Show version. –t0=<t0> The starting time of the transit in BJD or HJD. Only useful if user wants to have the time-of-secondary eclipse returned. –period=<p> The period of the transit in days. –pre_duration=<pre_duration> The duration of observations before transit/eclipse mid-time in hours. –transit_duration=<trans_dur> The duration of the transit in hours. –window_size=<win_size> The window size of the transit in hours [default: 1.0] –secondary If active, calculate phases for secondary eclipses (user needs to supply eccentricity, omega and inclination). –eccentricity=<ecc> The eccentricity of the orbit (needed for secondary eclipse constraints). –omega=<omega> The argument of periastron passage (needed for secondary eclipse constraints). –inclination=<inc> The inclination of the orbit (needed for secondary eclipse constraints). –winn_approx If active, instead of running the whole Kepler equation calculation, time of secondary eclipse is calculated using eq. (6) in Winn (2010; https://arxiv.org/abs/1001.2010v5) –get_secondary_time If active, calculation also returns time-of-secondary eclipse. Needs t0 as input.

exoctk.phase_constraint_overlap.phase_constraint_overlap.calculate_phase(period, pre_duration, window_size, t0=None, ecc=None, omega=None, inc=None, secondary=False, winn_approx=False, get_secondary_time=False)

Function to calculate the min and max phase.

Parameters

periodfloat

The period of the transit in days.

pre_durationfloat

The duration of observations before transit/eclipse mid-time in hours.

window_sizefloat

The window size of transit in hours. Default is 1 hour.

t0float

The time of (primary) transit center (only needed if get_secondary_time is True).

eccfloat

The eccentricity of the orbit (only needed for secondary eclipses).

omegafloat

The argument of periastron passage, in degrees (only needed for secondary eclipses).

incfloat

The inclination of the orbit, in degrees (only needed for secondary eclipses).

secondaryboolean

If True, calculation will be done for secondary eclipses.

winn_approxboolean

If True, secondary eclipse calculation will use the Winn (2010) approximation to estimate time of secondary eclipse — (only valid for not very eccentric and inclined orbits).

get_secondary_timeboolean

If True, return time of secondary eclipse along with the phase constraints.

Returns

minphasefloat

The minimum phase constraint.

maxphasefloat

The maximum phase constraint.

exoctk.phase_constraint_overlap.phase_constraint_overlap.calculate_pre_duration(transitDur)

Function to calculate the pre-transit hours to be spent on target as recommended by the Tdwell equation:

0.75 + Max(1hr,T14/2) (before transit) + T14 + Max(1hr, T14/2) (after transit) + 1hr (timing window)

The output is, thus, 0.75 + Max(1hr,T14/2) (before transit) + T14/2.

Parameters

transitDurfloat

The duration of the transit/eclipse in hours.

Returns

pretransit_durationfloat

The duration of the observation prior to transit/eclipse mid-time in hours.

exoctk.phase_constraint_overlap.phase_constraint_overlap.calculate_tsec(period, ecc, omega, inc, t0=None, tperi=None, winn_approximation=False)

Function to calculate the time of secondary eclipse.

This uses Halley’s method (Newton-Raphson, but using second derivatives) to first find the true anomaly (f) at which secondary eclipse occurs, then uses this to get the eccentric anomaly (E) at secondary eclipse, which gives the mean anomaly (M) at secondary eclipse using Kepler’s equation. This finally leads to the time of secondary eclipse using the definition of the mean anomaly (M = n*(t - tau) — here tau is the time of pericenter passage, n = 2*pi/period the mean motion).

Time inputs can be either the time of periastron passage directly or the time of transit center. If the latter, the true anomaly for primary transit will be calculated using Halley’s method as well, and this will be used to get the time of periastron passage.

Parameters

periodfloat

The period of the transit in days.

eccfloat

Eccentricity of the orbit

omegafloat

Argument of periastron passage (in radians)

incstring

Inclination of the orbit (in radians)

t0float

The transit time in BJD or HJD (will be used to get time of periastron passage).

tperifloat

The time of periastron passage in BJD or HJD (needed if t0 is not supplied).

winn_approximationboolean

If True, the approximation in Winn (2010) is used — (only valid for not very eccentric and inclined orbits).

Returns

tsecfloat

The time of secondary eclipse

exoctk.phase_constraint_overlap.phase_constraint_overlap.drsky(x, ecc, omega, inc)

Function whose roots we wish to find to obtain time of secondary (and primary) eclipse(s)

When one takes the derivative of equation (5) in Winn (2010; https://arxiv.org/abs/1001.2010v5), and equates that to zero (to find the minimum/maximum of said function), one gets to an equation of the form g(x) = 0. This function (drsky) is g(x), where x is the true anomaly.

Parameters

xfloat

True anomaly

eccfloat

Eccentricity of the orbit

omegafloat

Argument of periastron passage (in radians)

incfloat

Inclination of the orbit (in radians)

Returns

drskyfloat

Function evaluated at x, ecc, omega, inc

exoctk.phase_constraint_overlap.phase_constraint_overlap.drsky_2prime(x, ecc, omega, inc)

Second derivative of function drsky. This is the second derivative with respect to f of the drsky function.

Parameters

xfloat

True anomaly

eccfloat

Eccentricity of the orbit

omegafloat

Argument of periastron passage (in radians)

incfloat

Inclination of the orbit (in radians)

Returns

drsky_2primefloat

Function evaluated at x, ecc, omega, inc

exoctk.phase_constraint_overlap.phase_constraint_overlap.drsky_prime(x, ecc, omega, inc)

Derivative of function drsky. This is the first derivative with respect to f of the drsky function.

Parameters

xfloat

True anomaly

eccfloat

Eccentricity of the orbit

omegafloat

Argument of periastron passage (in radians)

incfloat

Inclination of the orbit (in radians)

Returns

drsky_primefloat

Function evaluated at x, ecc, omega, inc

exoctk.phase_constraint_overlap.phase_constraint_overlap.getE(f, ecc)

Function that returns the eccentric anomaly

Note normally this is defined in terms of cosines (see, e.g., Section 2.4 in Murray and Dermott), but numerically this is troublesome because the arccosine doesn’t handle negative numbers by definition (equation 2.43). That’s why the arctan version is better as signs are preserved (derivation is also in the same section, equation 2.46).

Parameters

ffloat

True anomaly

eccfloat

Eccentricity

Returns

Efloat

Eccentric anomaly

exoctk.phase_constraint_overlap.phase_constraint_overlap.getLTT(a, c, ecc, omega, inc, f)

Function that calculates the Light Travel Time (LTT) for eclipses and transit

This function returns the light travel time of an eclipse or transit given the orbital parameters, the semi-major axis of the orbit and the speed of light. Consistent units must be used for the latter two parameters. The returned time is in the units of time given by the speed of light input parameter.

Parameters

afloat

Semi-major axis of the orbit. Can be in any unit, as long as it is consistent with c.

cfloat

Speed of light. Can be in any unit, as long as it is consistent with a. The time-unit for the speed of light will define the returned time-unit for the light-travel time.

eccfloat

Eccentricity of the orbit.

omegafloat

Argument of periastron passage (in radians).

incstring

Inclination of the orbit (in radians)

ffloat

True anomaly at the time of transit and/or eclipse (in radians).

Returns

lttfloat

The light travel time, defined here as the time it takes for a photon to go from the planet at transit/eclipse to the plane in the sky where the star is located.

exoctk.phase_constraint_overlap.phase_constraint_overlap.getM(E, ecc)

Function that returns the mean anomaly using Kepler’s equation

Parameters

Efloat

Eccentric anomaly

ecc: float

Eccentricity

Returns

Mfloat

Mean anomaly

exoctk.phase_constraint_overlap.phase_constraint_overlap.phase_overlap_constraint(target_name, period=None, t0=None, pretransit_duration=None, transit_dur=None, window_size=None, secondary=False, ecc=None, omega=None, inc=None, winn_approx=False, get_secondary_time=False)

The main function to calculate the phase overlap constraints. We will update to allow a user to just plug in the target_name and get the other variables.

Parameters

target_namestring

The name of the target transiting planet.

periodfloat

The period of the transit in days.

t0float

The transit mid-time in BJD or HJD (only useful if time-of-secondary eclipse wants to be returned).

pretransit_durationfloat

The duration of the observations before transit/eclipse in hours.

transit_durfloat

The duration of the transit/eclipse in hours.

window_sizefloat

The window size of transit in hours. Default is 1 hour.

secondaryboolean

If True, phase constraint will be the one for the secondary eclipse. Default is primary (i.e., transits).

eccfloat

Eccentricity of the orbit. Needed only if secondary is True.

omegafloat

Argument of periastron of the orbit in degrees. Needed only if secondary is True.

incfloat

Inclination of the orbit in degrees. Needed only if secondary is true.

winn_approxboolean

If True, instead of running the whole Kepler equation calculation, time of secondary eclipse is calculated using eq. (6) in Winn (2010; https://arxiv.org/abs/1001.2010v5)

get_secondary_timeboolean

If True, this function also returns the time-of-mid secondary eclipse.

Returns

minphasefloat

The minimum phase constraint.

maxphasefloat

The maximum phase constraint.

tsecfloat

(optional) If get_secondary_time is True, the time of secondary eclipse in the same units as input t0.

Module contents