antaress.ANTARESS_grids.ANTARESS_coord module

coord_expos(pl_loc, coord_dic, inst, vis, star_params, pl_params, t_bjd, exp_time, data_dic, RpRs)

Exposure coordinates

Calculates temporal and spatial coordinates of planets at the start, mid, and end of an exposure.

Parameters:

TBD

Returns:

None

coord_expos_ar(ar_name, t_bjd, ar_prop, star_params, exp_dur, coord_par)

Exposure active region coordinates

Calculates temporal and spatial coordinates of active regions at the start, mid, and end of an exposure.

Parameters:

• ar_name (str) – name of the active region considered.

• t_bjd (float) – timestamp of the exposure considered. Needed to calculate the active region longitude.

• ar_prop (dict) – nominal properties of the active region considered.

• star_params (dict) – star properties.

• exp_dur (float) – optional, duration of the exposure considered. If left as None, only the active region properties at the center of the exposure will be computed. Otherwise, the active region properties at the start, center and end of exposure will be computed.

• coord_par (dict) – coordinates to store for the active region.

Returns:

None

calc_Kstar(params, star_params)

Keplerian semi-amplitude.

Calculates Keplerian semi-amplitude of the star induced by a given planet (in m/s).

The general formula is

\[K_\mathrm{prim} = (2 \pi G/P)^{1/3} M_\mathrm{sec} \sin(i_p) ((M_\mathrm{sec}+M_\mathrm{prim})^{1/3} / M_\mathrm{prim}) /\sqrt{1-e^2}\]

With \(K_\mathrm{prim}\) in km/s, G in \(m^3 kg^{-1} s^{-2}\), P in s, \(M_\mathrm{prim}\) and \(M_\mathrm{sec}\) in kg. Thus

\[\begin{split}K_\mathrm{prim} &= (212.91918458020422/P_\mathrm{days}^{1/3}) M_\mathrm{sec} \sin(i_p) ((M_\mathrm{sec}+M_\mathrm{prim})^{1/3}/M_\mathrm{prim}) / \sqrt{1-e^2} \\ &\mathrm{where\,} [ (2 \pi 6.67300\times10^{-11})^{1/3} 1.9891001\times10^{30} (1.9891001\times10^{30})^{1/3}]/[(24 \times 3600)^{1/3} (1.9891001\times10^{30})]/1000 = 212.91918458020422\end{split}\]

With \(P_\mathrm{days}\) in days, \(M_\mathrm{prim}\) and \(M_\mathrm{sec}\) in \(M_\mathrm{Sun}\). For a planet \(M_\mathrm{sec} = M_p << M_\mathrm{prim} = M_{\star}\), thus

\[K_{\star} \sim (2 \pi G/P)^{1/3} (M_p \sin(i_p)/M_{\star}^{2/3}) /\sqrt{1-e^2}\]

With \(K_{\star}\) in km/s, G in \(m^3 kg^{-1} s^{-2}\), P in s, \(M_p\) and \(M_{\star}\) in kg. Or

\[\begin{split}K_{\star} &= (0.20323137323712528/P_\mathrm{days}^{1/3}) (M_p \sin(i_p)/M_{\star}^{2/3}) /\sqrt{1-e^2} \\ &\mathrm{where\,} [ (2 \pi 6.67300\times10^{-11})^{1/3} 1.8986000\times10^{27}]/[(24 \times 3600)^{1/3} (1.9891001\times10^{30})^{2/3}]/1000 = 0.20323137\end{split}\]

With \(P_\mathrm{days}\) in days, \(M_p\) and \(M_{\star}\) in \(M_\mathrm{Sun}\). Or

\[K_{\star} = (0.02843112300449059/P_\mathrm{years}^{1/3}) (M_p \sin(i_p)/M_{\star}^{2/3}) /\sqrt{1-e^2}\]

With \(P_\mathrm{years}\) in years, \(M_p\) and \(M_{\star}\) in \(M_\mathrm{Sun}\).

Parameters:

TBD

Returns:

Kstar (float) – Keplerian semi-amplitude of the star from the planet (km/s)

calc_rv_star(coord_dic, inst, vis, system_param, gen_dic, bjd_exp, dur_exp, sysvel)

Stellar rv: for observations

Calculates the rv of the star in the stellar and sun barycentric rest frames.

The Keplerian rv of the star induced by a given planet is

\[rv(\mathrm{star/stellar \, CDM \,;\, from \, pl})= K_{\star} ( \cos(\nu+\omega_\mathrm{bar})+ e \cos(\omega_\mathrm{bar}) )\]

With \(K_{\star}\), \(\nu\), e and \(\omega_\mathrm{bar}\) specific to the planet. Radial velocity is negative when the planet is coming toward the observer, thus in the same frame as the observed rv tables.

Parameters:

TBD

Returns:

None

calc_rv_star_HR(pl_ref, system_param, kepl_pl, coord_dic, inst, vis, data_dic)

Stellar rv: for plots

Calculates the rv of the star in the sun barycentric rest frame, over a high-resolution phase table.

Specific to each visit, since the Keplerian rv is not the same if there are multiple planets.

Parameters:

TBD

Returns:

None

Kepler_func(Ecc_anom, Mean_anom, ecc)

Eccentric anomaly solver.

Finds the eccentric anomaly of the orbit using the mean anomaly and eccentricity.

\(M = E - e \sin(E)\)

Parameters:

• Ecc_anom (float) – Eccentric anomaly.

• Mean_anom (float) – Mean anomaly.

• ecc (float) – Eccentricity.

Returns:

delta (float) – equation to nullify

calc_mean_anom_TR(ecc, omega_bar)

Mean anomany at mid-transit.

Parameters:

• ecc (float) – Eccentricity.

• omega_bar (float) – Argument of periastron.

Returns:

Mean_anom_TR (float) – Mean anomany at mid-transit.

calc_true_anom(ecc, phase, omega_bar)

True anomaly.

Parameters:

• ecc (float) – Eccentricity.

• phase (1D array) – orbital phase.

• omega_bar (float) – Argument of periastron.

Returns:

• True_anom (1D array) – True anomany at given phases.

• Ecc_anom (1D array) – Eccentric anomany at given phases.

• Mean_anom (1D array) – Mean anomany at given phases.

calc_pl_coord(ecc, omega_bar, aRs, inclin, ph_loc, RpRs, lambda_rad, star_params, rv_LOS=False, omega_p=None)

Planet orbit

Calculates orbital planetary position and velocity, as well as eclipse condition.

References

• http://www.gehirn-und-geist.de/sixcms/media.php/370/Leseprobe.406372.pdf

• http://www.relativitycalculator.com/pdfs/RV_Derivation.pdf

• https://www.sciencedirect.com/topics/engineering/eccentric-anomaly

We calculate the perifocal coordinates of the planet, in cartesian coordinates relative to the star. The radial velocity \(rv(pl/star)\) (negative when the planet is coming toward us) is derived directly from these coordinates as

\[rv(pl/star) = - K_\mathrm{pl/star} ( \cos(\nu+\omega_\mathrm{bar})+e \cos(\omega_\mathrm{bar}) )\]

Kepler third’s law gives

\[\begin{split}P^2/a^3 &= 4 \pi^2 / (G (M_\mathrm{pl}+M_{\star})) \\ a &= ( G P^2 (M_{\star}+M_\mathrm{pl}) / (4 \pi^2) )^{1/3}\end{split}\]

Thus we can write the semi-amplitude of the planet Keplerian motion as

\[\begin{split}K_\mathrm{pl/star} &= 2 \pi a \sin(i_p)/(P \sqrt{1-e^2}) \\ K_\mathrm{pl/star} &= (2 \pi G/P)^{1/3} (M_{\star}+M_\mathrm{pl})^{1/3} \sin(i_p)/\sqrt{1-e^2}\end{split}\]

The radial velocity of the planet in the star rest frame can also be defined as

\[rv(pl/star) = rv(pl/CMD_{\star}) - rv(star/CMD_{\star})\]

And because the barycenter is fixed in its own frame:

\[\begin{split}& M_{\star} rv(star/CMD_{\star}) + M_\mathrm{pl} rv(pl/CMD_{\star}) = 0 \\ & M_{\star} rv(star/CMD_{\star}) + M_\mathrm{pl} (rv(pl/star)+rv(star/CMD_{\star})) = 0 \\ & rv(star/CMD_{\star})= - rv(pl/star) M_\mathrm{pl}/(M_{\star}+M_\mathrm{pl})\end{split}\]

Thus

\[\begin{split}rv(star/CMD_{\star}) &= K[star/CMD_{\star}] ( \cos(\nu+\omega_\mathrm{bar})+e \cos(\omega_\mathrm{bar}) ) \\ \mathrm{where\,} & K[star/CMD_{\star}] = K_\mathrm{pl/star} M_\mathrm{pl}/(M_{\star}+M_\mathrm{pl}) \\ & K[star/CMD_{\star}] = (2 \pi G/P)^{1/3} M_\mathrm{pl} \sin(i_p)/((M_{\star}+M_\mathrm{pl})^{2/3} \sqrt{1-e^2})\end{split}\]

With K in km/s, G in \(m^3 kg^{-1} s^{-2}\), P in s, \(M_\mathrm{pl}\) and \(M_{\star}\) in kg. Or (see calc_Kstar())

\[\begin{split}K[star/CMD_{\star}] &= (212.91918458020422/P_\mathrm{days}^{1/3}) M_\mathrm{pl,Msun} \sin(i_p)/((M_{\star,Msun} +M_\mathrm{pl,Msun})^{2/3} \sqrt{1-e^2}) \\ K[star/CMD_{\star}] &= (0.02843112300449059/P_\mathrm{yr}^{1/3}) M_\mathrm{pl,Msun} \sin(i_p)/((M_{\star,Msun} +M_\mathrm{pl,Msun})^{2/3} \sqrt{1-e^2})\end{split}\]

We can also write

\[\begin{split}rv(pl/CMD_{\star}) &= rv(pl/star) + rv(star/CMD_{\star}) \\ &= ( - K_\mathrm{pl/star} + K_\mathrm{pl/star} M_\mathrm{pl}/(M_{\star}+M_\mathrm{pl}) ) ( \cos(\nu+\omega_\mathrm{bar})+e \cos(\omega_\mathrm{bar}) ) \\ &= K[pl/CMD_{\star}] ( \cos(\nu+\omega_\mathrm{bar})+e \cos(\omega_\mathrm{bar}) ) \\ \mathrm{where\,} & K[pl/CMD_{\star}] = K_\mathrm{pl/star} ( M_\mathrm{pl}/(M_{\star}+M_\mathrm{pl}) - 1 ) \\ & K[pl/CMD_{\star}] = K_\mathrm{pl/star} ( (M_\mathrm{pl}-M_{\star})/(M_{\star}+M_\mathrm{pl}) ) \\ & K[pl/CMD_{\star}] = - (2 \pi G/P)^{1/3} (M_{\star}-M_\mathrm{pl}) \sin(i_p)/(\sqrt{1-e^2} (M_{\star}+M_\mathrm{pl})^{1/3} )\end{split}\]

If we assume that the atmospheric signal tracks the planet orbital velocity (ie, there is no atmospheric dynamics), then we can link the planet and star masses with this measurement. Doing as few assumptions as possible, the quantity we measure is

\[\begin{split}rv(pl/CDM_\mathrm{sun}) &= rv(pl/CMD_{\star}) + rv(CMD_{\star}/CDM_\mathrm{sun}) \\ &= - (2 \pi G/P)^{1/3} (M_{\star}-M_\mathrm{pl}) \sin(i_p)/(\sqrt{1-e^2} (M_{\star}+M_\mathrm{pl})^{1/3} ) + rv_\mathrm{sys}\end{split}\]

Parameters:

TBD

Returns:

None

calc_pl_coord_plots(n_pts_orbit, pl_params, unit='Rs')

Planet orbit: for plots.

Defines planetary orbit coordinates for plot and contact times. Coordinates are defined in the sky-projected orbital frame

\[\begin{split}X_\mathrm{sky} &= \mathrm{node \, line \, of \, orbital \, plane} \\ Y_\mathrm{sky} &= \mathrm{projection \, of \, the \, orbital \, plane \, normal} \\ Z_\mathrm{sky} &= \mathrm{LOS}\end{split}\]

Parameters:

TBD

Returns:

coord_orbit (array) – sky-projected coordinates.

calc_zLOS_oblate(x_st_sk, y_st_sk, istar_rad, RpoleReq)

LOS coordinate for oblate photosphere.

Calculates the Z coordinate (along the LOS) of an element at (X,Y) over the sky-projected photosphere (inclined star frame) of an oblate star. The Z coordinate is returned in the stellar hemispheres facing and opposite the observer.

Based on Barnes+2009, Eq. 13 and 14 with \(\Phi = \pi/2 - i_{\star}\). Beware that their Eq 14 is wrong, as \(1-f^2\) should be \((1-f)^2\)

Parameters:

TBD

Returns:

None

excl_plrange(cond_def, range_star_in, iexp, edge_bins, data_format)

Planet atmospheric masking.

Identifies spectral pixels contaminated by the planetary atmosphere, as requested in input. A common rv range is excluded for each spectral line in the requested planet atmosphere mask (see init_visit() for the definition of these ranges in other frames).

Parameters:

TBD

Returns:

None

calc_ar_coord(ar_prop_exp, ang_rad, lat_rad, long_rad, i_pos, istar, star_params)

Active region track

Calculates position of active regions across the stellar surface, in the aligned star rest frame.

Parameters:

TBD

Returns:

None

get_timeorbit(Tcenter, bjd_tab, param, exp_time_tab, conv_ang=False)

Exposure time and phase

Calculates time and phase coordinates of planets or active regions at the start, mid, and end of an exposure.

Parameters:

TBD

Returns:

None

conv_phase(coord_dic, inst, vis, system_param, ref_pl, pl_loc, phase_tab_in)

Planet phase conversion

Converts orbital phase of reference planet for another planet.

Parameters:

TBD

Returns:

None

calc_tr_contacts(RpRs, pl_params, stend_ph, star_params)

Transit contacts.

Calculates the orbital phase of the four transit contacts for the selected planet.

Parameters:

TBD

Returns:

None

eclipse_status(Dprojp_all, RpRs, lambda_rad, star_params, xp_sk_all, yp_sk_all, zp_sk_all)

Exposure eclipse status.

Identify planet transit and occulation status at a given orbital position.

• Post-occultation/pre-transit: ecl = -1

• Ingress of transit: ecl = +2

• Full transit: ecl = +3

• Egress of transit: ecl = +2

• Post-transit/pre-occultation: ecl = +1

• Ingress of occultation: ecl = -2

• Full occultation: ecl = -3

• Egress of occultation: ecl = -2

To be conservative, an exposure is considered out of the transit/occultation, or fully in-transit/occultation if it is such during the entire exposure. Input planet position either correspond to the center of the exposure, or to its (start,central,end) values.

Parameters:

TBD

Returns:

None

pl_limb_in_oblate_star(nlimb, RpRs, xp_st_sk, yp_st_sk, star_params)

Transit contacts.

Calculates the number of discretized planet limb points within the projected oblate stellar photosphere, for a given orbital position.

Parameters:

TBD

Returns:

None

is_ar_visible(istar, long_rad, lat_rad, ang_rad, f_GD, RpoleReq)

Active region visibility

Performs a rough estimation of the visibility of an active region, based on star inclination (istar), active region coordinates in star rest frame (long, lat) and active region angular size (ang). To do so, we discretize the active region edge and check if at least one point is visible. The visibility criterion is derived as follows.

Let \(\mathrm{P} = (x_{\mathrm{st}}, y_{\mathrm{st}}, z_{\mathrm{st}})\) be a point on the stellar surface, in the star rest frame (i.e. X axis parallel to the star equator and Y axis along the stellar spin), that is on the edge of an active region.

Expressing P in spherical coordinates gives

\[& x_{\mathrm{st}} = \mathrm{sin}(long) \mathrm{cos}(lat) & y_{\mathrm{st}} = \mathrm{sin}(lat) & z_{\mathrm{st}} = \mathrm{cos}(long) \mathrm{cos}(lat)\]

Moving P to the ‘inclined’ star rest frame gives

\[& x_{\mathrm{sky}} = x_{\mathrm{st}} & y_{\mathrm{sky}} = \mathrm{sin}(i_*) y_{\mathrm{st}} - \mathrm{cos}(i_*) z_{\mathrm{st}} & z_{\mathrm{sky}} = \mathrm{cos}(i_*) y_{\mathrm{st}} + \mathrm{sin}(i_*) z_{\mathrm{st}}\]

The condition for P to be visible is then \(z_{\mathrm{sky}} > 0\) or

\[& \mathrm{cos}(i_*) \mathrm{sin}(lat) + \mathrm{sin}(i_*) \mathrm{cos}(long) \mathrm{cos}(lat) > 0\]

WIP : Doing this with gravity darkening

Parameters:

• istar (float) – stellar inclination (in radians)

• long_rad (float) – active region longitude (in radians)

• lat_rad (float) – active region latitude (in radians)

• ang_rad (float) – active region half-angular size (in radians)

• f_GD (float) – oblateness coefficient.

• RpoleReq (float) – pole to equatoral radius ratio.

Returns:

ar_visible (bool) – active region visibility criterion.

frameconv_skyorb_to_skystar(lambd, x_skorb, y_skorb, z_skorb)

Frame: sky-projected, orbital to stellar.

Converts coordinates from the classical sky-projected orbital frame, to the sky-projected (inclined) stellar frame. Frame is rotated around the \(Z_\mathrm{LOS}\) axis (the LOS, which remains unchanged), by angle \(\lambda\) counted \(>0\) counterclockwise from the \(X_\mathrm{sky,star}\) to the \(X_\mathrm{sky}\) axis, or from the \(Y_\mathrm{sky,star}\) to the \(Y_\mathrm{sky}\) axis, in the \(XY_\mathrm{sky}\) plane.

\[\begin{split}X_\mathrm{sky,star} &= \mathrm{sky-projected \, stellar \, equator} \\ Y_\mathrm{sky,star} &= \mathrm{sky-projected \, stellar \, spin} \\ Z_\mathrm{sky,star} &= \mathrm{LOS}\end{split}\]

Parameters:

TBD

Returns:

None

frameconv_skystar_to_skyorb(lambd, x_skst, y_skst, z_skst)

Frame: sky-projected, stellar to orbital.

Converts coordinates from the sky-projected (inclined) stellar frame to the classical sky-projected orbital frame.

Parameters:

TBD

Returns:

None

frameconv_skystar_to_star(xin, yin, zin, istar)

Frame: sky-projected stellar to stellar.

Converts coordinates from the sky-projected (inclined) stellar frame to the star frame. Frame is rotated around the \(X_\mathrm{sky,star}\) axis (which remains unchanged), by angle \(i_{\star}\) counted \(>0\) counted counterclockwise from the \(Z_\mathrm{sky,star}\) to the \(Y_\star\) axis in the \(YZ_\mathrm{sky,star}\) plane.

\[\begin{split}X_\mathrm{star} &= \mathrm{star \,equator} \\ Y_\mathrm{star} &= \mathrm{star \, spin} \\ Z_\mathrm{star} &= \mathrm{complements \, frame}\end{split}\]

Parameters:

TBD

Returns:

None

frameconv_star_to_skystar(xin, yin, zin, istar)

Frame: stellar to sky-projected stellar.

Converts coordinates from the star frame to the sky-projected (inclined) stellar frame.

Parameters:

TBD

Returns:

None