Projecc: Exoplanet Position Predictor

• Projecc is an open-source Python package that transforms published exoplanet orbital solutions into accurate sky-plane predictions for direct imaging.
• It employs Monte Carlo sampling with Gaussian priors and Keplerian formalism to estimate projected separation, phase angle, and positional uncertainty.
• The tool directly supports observational planning by informing dark-hole placement and interpreting non-detections in reflected-light imaging.

Searching arXiv for the specified paper to ground the article and citation. projecc is an open-source Python package for predicting where a known exoplanet is likely to appear on the sky at a specified epoch, given a published orbital solution and associated parameter uncertainties. Its scope is deliberately narrow: it is explicitly not an orbit-fitting code, does not ingest RV time series, astrometric measurements, or direct-imaging astrometry to derive orbital elements, and instead propagates literature orbital solutions into posterior samples of sky-plane location, projected separation, viewing phase angle, and related kinematic quantities. The package is motivated by direct imaging of known planets, especially reflected-light observations with ELT-class facilities, the Roman Coronagraph Instrument, and future missions such as the Habitable Worlds Observatory, where efficient use of observing time depends on knowing where the planet is likely to be, whether it lies outside the inner working angle, and whether its phase geometry is favorable (Pearce et al., 8 Sep 2025).

1. Definition, scope, and observational motivation

projecc was written to answer two practical questions for direct-imaging campaigns of known planets: given a published orbit, how well the planet’s sky position is known on a specific date, and how that uncertainty should inform observation scheduling and instrument configuration. The package takes orbital solutions typically derived from radial velocity and/or astrometry and produces posterior samples for the planet’s offset from the star in RA and Dec at a given time, the projected separation in milliarcseconds, the viewing phase angle relevant for reflected-light contrast, and related 3-D position, velocity, and acceleration.

The scientific context is the transition from indirect detection to direct imaging and characterization of cold, mature planets in thermal emission and reflected light. The facilities cited for this use case include ELT-PCS, GMagAO-X, PSI, the Roman Coronagraph Instrument, and the Habitable Worlds Observatory. Because reflected-light observations target contrasts of approximately $10^{-7} - 10^{-10}$, direct-imaging efficiency depends on placing the dark hole or other high-contrast region where the planet is most likely to be, observing near maximum elongation and favorable phase angle, and accounting for orbital motion during long campaigns.

A central motivation is that many promising targets are already known from RV or astrometry but lack orbital parameters precise enough for reliable direct-imaging ephemerides. The paper identifies $T_0$ and $\omega$ as especially problematic in this regard. projecc is therefore a community preparation tool rather than a fitting framework. The package is distributed through PyPI and GitHub, and is accompanied by the GRIP web app, described as the “Ground-based Reflected-light Imaging Planner.”

2. Orbital formalism and coordinate conventions

The package adopts a standard Keplerian description following Murray and Dermott’s conventions, but it makes the coordinate choices explicit in order to avoid the common inconsistencies that arise when combining RV, astrometry, and direct-imaging conventions. In the orbital plane $(\hat x,\hat y,\hat z)$, the origin is the system barycenter, $+\hat x$ points from the barycenter to periastron, $+\hat y$ is $90^\circ$ ahead of $+\hat x$ in the orbital plane, and $+\hat z$ is the orbit normal along the angular momentum vector. The osculating elements used are $a$, $T_0$0, $T_0$1, $T_0$2, $T_0$3, $T_0$4, and $T_0$5, supplemented by $T_0$6, $T_0$7 or $T_0$8, parallax $T_0$9, and optionally planet radius $\omega$0.

A recurring ambiguity in the literature is whether the published argument of periastron refers to the star or the planet. projecc assumes by default that published $\omega$1 refers to the star and converts it using

$\omega$2

The package also adopts sky-plane coordinates $\omega$3 with $\omega$4 toward $\omega$5Dec, $\omega$6 toward $\omega$7RA, and $\omega$8 toward the observer, which is opposite the usual RV sign convention. This explicit convention is significant because a sign or $\omega$9 mismatch can displace the predicted sky position and phase behavior.

The orbital-plane position at true anomaly $(\hat x,\hat y,\hat z)$0 is written as

$(\hat x,\hat y,\hat z)$1

with

$(\hat x,\hat y,\hat z)$2

where $(\hat x,\hat y,\hat z)$3 is $(\hat x,\hat y,\hat z)$4 or $(\hat x,\hat y,\hat z)$5 depending on whether the star’s or planet’s barycentric orbit is desired, and $(\hat x,\hat y,\hat z)$6. The true anomaly is obtained from the eccentric anomaly $(\hat x,\hat y,\hat z)$7,

$(\hat x,\hat y,\hat z)$8

with $(\hat x,\hat y,\hat z)$9 determined by Kepler’s equation,

$+\hat x$0

projecc uses the fast cubic approximation of Mikkola (1987) to solve Kepler’s equation.

Projection to the observer frame is performed with rotation matrices about the $+\hat x$1 and $+\hat x$2 axes,

$+\hat x$3

so that

$+\hat x$4

The package then converts $+\hat x$5 and $+\hat x$6 from au to RA and Dec offsets in mas using the parallax and forms the projected separation

$+\hat x$7

For reflected-light planning, projecc also computes the viewing phase angle following Madhusudhan and Burrows (2012),

$+\hat x$8

Here $+\hat x$9 corresponds to full phase, $+\hat y$0 to quadrature, and $+\hat y$1 to crescent phases. In the web-app context, phase angle can be mapped to a Lambertian contrast model,

$+\hat y$2

using a fiducial geometric albedo and a radius estimated from mass through an empirical mass-radius relation. The paper states that this contrast model is used primarily in the target-list and web-app context rather than as a core part of the package API.

3. Probabilistic model, classes, and outputs

The probabilistic engine treats orbital elements as random variables with specified priors and uses Monte Carlo sampling to generate orbit realizations at a chosen epoch. In the version described, the principal assumption is that parameters are independent and Gaussian, except that $+\hat y$3 and $+\hat y$4 may be drawn from specified non-Gaussian priors. The main input distributions are Gaussian $+\hat y$5 for $+\hat y$6, $+\hat y$7, $+\hat y$8, $+\hat y$9, $90^\circ$0, $90^\circ$1, $90^\circ$2 or $90^\circ$3, and $90^\circ$4; inclination may be a user-supplied Gaussian or a prior uniform in $90^\circ$5 over a chosen range; and $90^\circ$6 may be fixed, Gaussian, or uniform on $90^\circ$7.

Sampling proceeds by drawing $90^\circ$8 orbit realizations, with a default $90^\circ$9. For each draw, the code samples the parameters, computes $+\hat x$0, $+\hat x$1, $+\hat x$2, and $+\hat x$3, evaluates the orbital-plane and sky-plane coordinates, and then derives RA and Dec offsets, projected separation, phase angle, and kinematic quantities. The resulting point cloud is a Monte Carlo approximation to the posterior distribution of planet position conditional on the adopted priors. The package handles RV-only cases by drawing $+\hat x$4, and if inclination is unconstrained, by drawing from a uniform $+\hat x$5 prior over a user-selected interval; for RV+astrometry or astrometry-only cases, $+\hat x$6 and $+\hat x$7 can be supplied directly.

The code structure centers on two Python classes. Planet stores the orbital and system-parameter distributions, including tuples $+\hat x$8 for $+\hat x$9, $+\hat z$0, $+\hat z$1, $+\hat z$2, $+\hat z$3, $+\hat z$4, $+\hat z$5 or $+\hat z$6, and parallax. OrbitSim is constructed from a Planet instance, an epoch $+\hat z$7 in BJD, and a sample count $+\hat z$8; it performs the Monte Carlo calculation and stores the outputs.

For each epoch and planet, OrbitSim stores pos, an $+\hat z$9 array of sky-frame positions in au with pos[i,0] = X, pos[i,1] = Y, and pos[i,2] = Z; vel, an $a$0 array of 3-D velocities in km s$a$1; and acc, an $a$2 array of 3-D accelerations in km s$a$3 yr$a$4. It also provides derived RA and Dec offsets in mas, projected separation in mas or $a$5, and phase angle in degrees. Visualization utilities include RA-versus-Dec scatter plots color-coded by phase angle, contours enclosing 68%, 95%, and 99.7% of samples, and normalized 2-D probability density maps built with scipy.stats.gaussian_kde (Pearce et al., 8 Sep 2025).

A common misconception addressed directly in the paper is that projecc is an ephemeris-fitting or data-analysis framework. It is not. It requires a prior orbit solution from the literature or from another fitting pipeline and propagates that solution into on-sky distributions.

4. Observational planning and the GRIP interface

The package is designed for direct observational use rather than abstract orbit visualization. One application is scheduling near maximum elongation: a nominal best date can be inferred from mean orbital elements, and projecc can then show whether that date remains advantageous once the uncertainties in $a$6, $a$7, and other elements are propagated. Another application is dark-hole placement. If a coronagraph delivers high contrast over a defined annulus, wedge, or other region, the observer can estimate what fraction of samples falls in that accessible region at a given epoch. The same framework exposes the tradeoff between projected separation and reflected-light brightness, since large separation is often associated with phase angles that reduce flux.

The paper also emphasizes the interpretation of non-detections. If the posterior sky-position distribution is broad, a non-detection at a nominally favorable epoch may indicate only that the planet was too close to the star or at an unfavorable phase angle, rather than that its albedo, radius, or atmospheric properties are constrained. This point is central to the Proxima Centauri b analysis.

The associated Streamlit web app, referred to as GRIP and also described as “getagrip.space,” acts as a GUI front-end to the package. It provides an RV-planet target list for reflected-light imaging derived from the NASA Exoplanet Archive, comprising approximately 400 RV planets within 70 pc that are filtered to have full orbital information and to be accessible from the southern hemisphere. For a selected telescope diameter and wavelength, the app plots maximum projected separation in $a$8, Lambertian flux contrast versus separation, planet radius as marker size, and phase angle at maximum elongation as marker color.

The app also allows direct execution of projecc without local installation. Orbital parameters may be entered manually as Gaussian $a$9 values or selected from pre-loaded literature solutions for several systems, including GJ 876 b, Proxima b, and selected Roman CGI targets. The user can choose a date or request the time of maximum separation and may specify an aperture radius such as $T_0$00, after which the app computes the fraction of simulated positions within that aperture. Outputs include a phase-colored RA-Dec scatter plot, contour overlays, and summary statistics such as the fraction in the aperture, the standard deviation of the separation normalized by expected separation, and the parameter values used.

5. Case studies: GJ 876 b and Proxima Centauri b

The paper’s first case study is GJ 876 b, a nearby M-dwarf system with strong RV signals, long observing baselines, and published constraints from RV, HST FGS astrometry, and Gaia DR3 NSS. Three orbit solutions are compared for prediction on 2025-04-09 near an expected maximum elongation: Rivera et al. (2010), an RV-only Keck/HIRES solution; Benedict et al. (2002), a joint RV plus HST astrometry solution; and a Gaia DR3 NSS astrometric solution converted from Thiele-Innes constants using ESA’s NSS tools.

For the Rivera RV-only solution, the unconstrained $T_0$01 is drawn uniformly, producing a ring of points in the sky plane at nearly fixed separation. Because the chosen date is near maximum elongation, the samples are near quadrature phase and the uncertainty is concentrated in position angle rather than separation. For the Benedict RV-plus-astrometry solution, the constraints on $T_0$02 and $T_0$03 collapse the ring into a localized probability-density blob with narrowly constrained separation. The Gaia NSS solution produces a somewhat broader region but remains largely consistent with the others within approximately $T_0$04, while also illustrating that astrometry without RV cannot fully break the degeneracy in $T_0$05 and $T_0$06. The three solution families intersect in a compact region a few $T_0$07 from the star at $T_0$08 for an ELT or GMT. The paper interprets this as evidence that GJ 876 b is a strong reflected-light target and that combining RV and astrometry is operationally important (Pearce et al., 8 Sep 2025).

The second case study is Proxima Centauri b, identified as a prime habitable-zone target around the nearest star. The analysis uses published RV fits from Faria et al. (2022) and Suárez Mascareño et al. (2020), with the latter adopted for the main projecc demonstration because it provides smaller quoted uncertainties on the timing parameters. The authors convert the timing information into $T_0$09, transform $T_0$10 to $T_0$11, treat eccentricity and period as Gaussians with the quoted errors, assume an inclination prior because no direct inclination constraint exists, and fix $T_0$12 for clarity. They then predict the sky position on 2025-04-16, the date when the mean solution suggests maximum elongation.

The resulting posterior cloud is broad even under the fixed-node simplification. For a $T_0$13 ELT-like telescope at $T_0$14, approximately 7% of realizations place the planet closer than $T_0$15 at that date; for GMT at $T_0$16, approximately 25% are inside $T_0$17; and for a $T_0$18 telescope such as Magellan/MagAO-X, approximately 19% are inside $T_0$19, effectively unobservable. The phase-angle distribution is also unfavorable relative to the nominal expectation: although maximum elongation suggests $T_0$20, 34% of samples have $T_0$21, where the Lambertian contrast is approximately half that at quadrature, and 11% have $T_0$22, where the contrast is more than ten times lower than at quadrature. The paper’s interpretation is that a single non-detection under current orbit uncertainties would be highly ambiguous because geometry alone could explain it.

The paper identifies the dominant contributors to this positional uncertainty, once inclination is assumed, as the uncertainty in periastron time $T_0$23 and the uncertainty in $T_0$24. To quantify the precision requirements, the authors shrink $T_0$25 and $T_0$26 numerically, scanning $T_0$27 from 1 to 34 hours and $T_0$28 from $T_0$29 to $T_0$30. For each pair, they compute the fraction of Monte Carlo samples lying within a circular aperture of radius $T_0$31 centered on the expected location from the mean solution at maximum elongation. They infer that GMT requires approximately $T_0$32 hr and $T_0$33 for a 50% chance that the planet lies within $T_0$34 of the expected location, while ELT requires the more stringent $T_0$35 hr and $T_0$36. A further demonstration shows that artificially reducing the Suárez Mascareño uncertainties to $T_0$37 hr and $T_0$38 collapses the cloud into a compact region near the nominal maximum-elongation position. This suggests that the limiting factor for high-efficiency reflected-light imaging of Proxima Centauri b is not only angular resolution or contrast, but orbit precision itself.

6. Assumptions, limitations, and projected development

The current implementation makes a strong approximation: each orbital parameter is treated as independent and Gaussian, except for custom priors on $T_0$39 and $T_0$40. The paper notes that real orbit posteriors are often asymmetric, multimodal, strongly correlated, and in some cases biased. Eccentricity is singled out as a parameter for which these issues are especially common. As a result, a $T_0$41-only representation can misestimate the true uncertainty in sky position. The authors state that this approximation may be acceptable for tightly constrained systems, but may be critical for borderline cases such as Proxima Centauri b.

A second limitation concerns incomplete or ambiguous literature solutions. Some papers provide mean anomaly at a reference epoch rather than $T_0$42, some provide only period and phase, and some omit $T_0$43 entirely; projecc therefore requires a reconstructed and well-defined periastron time. The literature also frequently fails to specify whether $T_0$44 is defined for the star or planet, or adopts an opposite line-of-sight sign convention. If these conventions are not corrected, the predicted sky position and phase curve can be shifted by $T_0$45 in true-anomaly space. RV-only fits additionally cannot constrain $T_0$46 or the sign of $T_0$47, so any on-sky prediction in such cases necessarily depends on assumed priors.

A third limitation is ephemeris degradation. The paper states that projecc currently assumes that published uncertainties remain valid indefinitely, whereas in reality ephemeris errors grow with time from the epoch of the last constraining data. A Monte Carlo experiment on the GJ 876 b RV-only fit shows that when uncertainties are propagated forward over approximately 100 periods, the uncertainties in $T_0$48, $T_0$49, $T_0$50, and $T_0$51 grow substantially, and by roughly 10 to 25 periods some parameters become effectively unconstrained. The authors conclude that even apparently well-constrained predictions remain reliable only for a few years after the last constraining data and recommend obtaining updated RV or astrometric measurements close to the imaging epoch for high-value reflected-light campaigns (Pearce et al., 8 Sep 2025).

The package also cannot diagnose model misspecification in the source orbit solution. A published orbit may be precise yet inaccurate because of limited temporal baseline, additional companions, or underestimated systematics. The paper gives the example of $T_0$52 Indi Ab, where early RV-plus-Gaia fits mis-predicted the position by a factor of two in separation and by a hemisphere in position angle. projecc can expose whether an adopted solution implies a wide or tight sky-position posterior, but it cannot determine whether the original fit is physically or statistically flawed.

Planned upgrades address these limitations directly. The authors propose support for full posterior samples and covariance matrices rather than only Gaussian summaries, with possible interfaces to orbit-fitting packages such as orvara, RadVel, orbitize!, and octofitter. They also propose instrument-aware planning capabilities, including explicit dark-hole geometries such as EFC wedges, Lyot annuli, and Roman CGI SPC/HLC dark holes, together with computation of the fraction of orbit samples inside the dark hole as a function of time. A better treatment of time-dependent uncertainties is also planned, including explicit propagation of ephemeris growth and warnings when observations are scheduled far beyond the baseline of the original fit.

More broadly, projecc functions as a coordination layer between orbit-fitting teams and imaging teams. It provides a quantitative way to prioritize orbit-refinement campaigns, to assess how much improvement in $T_0$53, $T_0$54, $T_0$55, or $T_0$56 is required to achieve a desired detection probability, and to communicate positional predictions in a form directly relevant to high-contrast imaging. A plausible implication is that, as reflected-light imaging moves from feasibility studies to execution on ELTs, Roman CGI, and eventually HWO, the value of orbit solutions will increasingly depend not only on parameter estimates themselves but on whether those solutions can be translated into reliable, time-specific sky-plane posteriors.