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