Primary Eclipses: Using the Phase-Constraint Calculator¶
In the example above, the phase-constraint calculator returned the minimum and maximum phases for the exoplanet under study given only the planet name and the size of the window we were aiming to.
How Did It Do That?¶
In the background, the phase-constraint package automatically queries the exoplanet properties from exo.MAST given only the planet’s name. Using this, it retrieves the properties of interest (period, \(\mathcal P\), and total transit duration, \(\mathcal {T}_{14}\), in this case) and, by default, assumes the observer wants to start the observations at the very least a time:
\(\mathcal {T}_{pre} = 0.75 + \textrm{MAX}(1, {T}_{14}/2) + {T}_{14}/2\) hours
prior to mid-transit in this case. This time, by the way, is not arbitrary. Overall, the recommended (e.g., see this JWST observation planning step-by-step tutorial) time to spend on a target for a transit/eclipse observation is the above time \(\mathcal T_{pre}\) prior to the mid-transit time, and \(\mathcal {T}_{post} = {T}_{14}/2 + MAX(1, {T}_{14}/2) + {T}_{W}\) hours post mid-transit where \(\mathcal {T}_{W}\) is the phase-constraint window (one hour in our example above). Using the retrieved properties for WASP-18b shown above, we can understand how the calculation was done in the background. The transit duration is \(\mathcal {T}_{14} = 2.14368\) hours; the period is \(\mathcal P = 0.94124 = 22.58976\) hours. The time \(\mathcal {T}_{pre}\) is, thus, \(\mathcal {T}_{pre}\approx 2.89368\), which in phase-space units is
\(\mathcal {T}_{pre}/P \approx 0.128097\).
APT assumes the transit event is always located at phase 1 (or zero, whichever is more comfortable). Thus:
Maximum phase = \(\mathcal 1 - {T}_{pre}/P \approx 0.871903\),
which is exactly the maximum phase retrieved by the calculation. The minimum phase is simply one hour earlier in phase space. This gives:
Minimum phase = \(\mathcal 1 - ({T}_{pre}+1)/P \approx 0.827635\),
again, exactly the minimum phase quoted above.
Modifying Phase-Constraint Parameters¶
The phase-constraint calculator allows to ingest a number of variables into the calculation in order to give control to the user in terms of the calculations they want to make. For instance, the pre-transit duration discussed above, \(\mathcal T_{pre}\), can be changed by the user. This is done using the pretransit_duration variable. Suppose we wanted to retrieve the phase-constraint that corresponds to a pre-transit duration of 4 hours instead. We can simply do:
minp, maxp = pc.phase_overlap_constraint('WASP-18b', window_size = 1., pretransit_duration = 4.)
Retrieved period is 0.94124. Retrieved t0 is 58374.669900000095.
Performing calculations with Period: 0.94124, t0: 58374.669900000095, ecc: None, omega: None degs, inc: None degs.
MINIMUM PHASE: 0.7786607737311064, MAXIMUM PHASE: 0.8229286189848852
Of course, that is not the only parameter we can change. In fact, every transit parameter of interest can be ingested to the phase_overlap_constraint function, in whose case the user-defined properties will override the exo.MAST ones. Let’s use, for instance, the ephemerides found for WASP-18b by Shporer et al. (2019) - \(\mathcal P = 0.941452419\), \(\mathcal {t}_{0} = 2458002.354726\)
minp, maxp = pc.phase_overlap_constraint('WASP-18b', window_size = 1., period = 0.941452419, t0 = 2458002.354726)
Retrieved transit/eclipse duration is: 2.14368 hrs; implied pre mid-transit/eclipse on-target time: 2.89368 hrs.
Performing calculations with Period: 0.941452419, t0: 2458002.354726, ecc: None, omega: None degs, inc: None degs.
MINIMUM PHASE: 0.8276740668009621, MAXIMUM PHASE: 0.8719319239435721
Note how they are only slightly differnt than the ones retrieved from exo.MAST! One important detail in the above calculation, is that the time-of-transit center is of no use in phase-space because, by definition, for APT this is at phase equals 1. This means one could put any place holder value for \(\mathcal {t}_{0}\), and the calculation would result in the exact same values:
minp, maxp = pc.phase_overlap_constraint('WASP-18b', window_size = 1., period = 0.941452419, t0 = -1)
Retrieved transit/eclipse duration is: 2.14368 hrs; implied pre mid-transit/eclipse on-target time: 2.89368 hrs.
Performing calculations with Period: 0.941452419, t0: -1, ecc: None, omega: None degs, inc: None degs.
MINIMUM PHASE: 0.8276740668009621, MAXIMUM PHASE: 0.8719319239435721
Why does the phase-constraint overlap receives the time-of-transit center at all in the calculation? This will become clearer in the next section.