Orbit methods
Provisional
May change in any 0.4.x release without a deprecation cycle. virgil.orbit_search, virgil.epochs, virgil.aliases, virgil.arcs and virgil.tempering are provisional in the whole; the virgil.orbits helpers below (orientation priors to the position and RV terms) are stable (see stability).
Status. The thresholds behind the alias, no-orbit, label-swap and resolved-primary verdicts are in nats and are not yet calibrated against a null distribution, so read them as indications and not as Bayes factors. Tempering, the short-arc search, the alias-band search and the night-outlier mixture are virgil's own designs without a published source or an independent end-to-end validation; tempering is opt-in until 0.5 (temper=True; the default is untempered); its check currently warns outside a fixed range of the factor, 0.5 to 2.
The methods behind the helpers of virgil.orbits. Angle and sign conventions are on the conventions page, and Orbits from interferometric data runs the orbit pipeline and the functions underneath it end to end.
Orientation priors
An orbit's node \(\Omega\) and periastron \(\omega\) wrap at 0°/360°, and positions alone cannot tell \((\Omega, \omega)\) from \((\Omega + 180°, \omega + 180°)\). orientation_priors therefore returns AngleVector priors on the well-defined angles, so that exact symmetries become single points rather than separate modes:
positions_only=True: \(2\Omega\) (that is, \(\Omega\) modulo 180°) under"two_Omega", and the longitude of periastron \(\varpi = \Omega + \omega\) under"varpi". Both twins \((\Omega, \omega)\) and \((\Omega + 180°, \omega + 180°)\) have the same \(2\Omega\) and \(\varpi\), so the two modes collapse to one.positions_only=False, when radial velocities or other data fix the node:"Omega"and"varpi".
Near face-on the positions fix \(\varpi\) but not \(\Omega\) and \(\omega\) separately, so \(\varpi\) is well measured and \(\Omega\) broad. Build the orbit with KeplerOrbit.from_varpi.
The angles are uniform, which together with a prior uniform in \(\cos i\) is the invariant (Haar) prior on the orbit's orientation: \((\Omega, \omega) \to (2\Omega, \varpi)\) is linear with a constant Jacobian, so uniform \((\Omega, \omega)\) is uniform \((2\Omega, \varpi)\). With inclination=True the call also returns IsotropicInclination (density \(\propto \sin i\) on 0° to 180°) under "inc", which gives the full isotropic prior in one call. It is off by default so that code placing its own prior on inc keeps the keys it had.
Starting orbits from positions
At fixed period \(P\), eccentricity \(e\) and time of periastron \(T\), the sky positions are linear in the four Thiele–Innes constants, so each point of a \((P, e, T)\) grid is an exact weighted least-squares solve. starting_orbits solves every grid point and returns the lowest-\(\chi^2\) orbits. This needs no random restarts and handles the several minima of a short arc. Refine the best orbits with a fit to the visibilities or the positions. Every returned orbit has \(0 \le \Omega < 180°\), and \((\Omega + 180°, \omega + 180°)\) fits equally well.
Equal-flux binaries (sign_free=True). A binary of nearly equal fluxes has closure phases and \(V^2\) that are the same for \((\mathrm{dra}, \mathrm{ddec})\) and \((-\mathrm{dra}, -\mathrm{ddec})\), so the sign of each epoch's position is arbitrary. At fixed \((P, T, e)\) the positions are \(s_i M u_i\) with the unit-orbit points \(u_i\) known and the \(2\times2\) matrix \(M\) (the Thiele–Innes constants) unknown. Two epochs fix \(M\) up to one relative sign, so for the best-conditioned pairs of epochs and both relative signs, \(M\) is solved, every sign is set to the one that agrees with \(M u_i\), and the weighted fit is repeated twice on the signed positions. The result is the lowest \(\chi^2\); the global sign (the point reflection of the whole orbit) stays free, so the orbit returned and its reflection (\(\omega + 180°\)) fit equally well.
Period grids
A period that is wrong by \(\delta P\) drifts by \(T\,\delta P / P^2\) cycles over the time baseline \(T\), so trial periods must be spaced by no more than \(\delta P = P^2 / (kT)\) for the best of them to stay within a fraction of a cycle of the truth at every epoch. That is a uniform grid in frequency \(1/P\) with a step of \(1/(kT)\), which puts many more periods at short periods than a log-spaced grid and does not miss short-period orbits on a long baseline. period_grid builds it; neighbouring trial periods drift apart by \(1/k\) of a cycle over the baseline.
The default \(k = 9\) puts the true period within half a step of a trial period. Once the trial times of periastron have centred the phase, its error is at most \(1/(4k) = 1/36\) of a cycle at the ends of the baseline: one step of the default n_phase = 36 grid of times of periastron, so the two grids are about equally fine. This is finer than ARMADA's rule, \(P = 2fT/n\) with \(f = 3\) (\(k = 6\)), and The Joker's resolution, \(\delta P = 4P^2/(2\pi T)\) (\(k = \pi/2\)). For \(P = 5\)–20 d over \(T = 410\) d, ARMADA's rule gives about 370 periods and \(k = 9\) about 550.
Position angle at a reference epoch
Astrometry measures the position angle \(\theta\) at an epoch directly, so KeplerOrbit.from_position_angle replaces the time of periastron by \(\theta\) at t_ref (as in Octofitter), which suits short arcs. With \(\varphi = \theta - \Omega\), the argument of latitude \(u = \omega + f\) at t_ref follows from \((\cos\varphi, \sin\varphi) \propto (\cos u, \sin u \cos i)\), that is \(u = \operatorname{atan2}(\sin\varphi / \cos i,\ \cos\varphi)\). Then the true anomaly is \(f = u - \omega\), the eccentric and mean anomalies \(M\) follow, and dt_peri \(= -MP/2\pi\) (in \([-P/2, P/2)\)). Sample \(\theta\) as an AngleVector and add position_angle_prior to the likelihood terms, so that the prior stays uniform in the time of periastron.
The map is singular at \(i = 90°\), where the position angle takes only two values (\(\Omega\) and \(\Omega + 180°\)) and does not fix the phase; a concrete inc of 90° is rejected. Near edge-on it is badly conditioned: keep dt_peri, or use StateVectorOrbit.
Position calibration terms
PositionData.term takes north_angle= and plate_scale=, names of fitted values holding a dataset's North angle \(\delta\) (degrees, added to every measured position angle) and plate scale \(m\) (a factor, 1 when calibrated), after Octofitter. As for the RV jitter, each is a key of priors (which a function model must accept and may ignore), and each dataset needs its own names. Their priors must be stated; there is no default width. The invariant priors (uniform on the circle for \(\delta\), log-uniform for \(m\)) leave each one degenerate with the orbit's orientation and size when a single dataset is fitted, so a Gaussian such as Normal(0, 0.1) for \(\delta\) and Normal(1, 1e-3) for \(m\) is strong information and should come from the instrument's astrometric calibration. The terms do not change the likelihood's normalization, so a least-squares fit keeps its form.
Scale-marginalized scoring
The score. Each observable block \(b\) of a dataset (visibilities, closure phases, each extra observable) has an unknown factor \(s_b\) on its quoted errors. Integrating it out under its Jeffreys prior \(1/s_b\) (Jeffreys 1946) gives, up to a constant, \(m = -\sum_b (\nu_b/2)\ln\chi^2_b\), where \(\chi^2_b\) is the block's \(\chi^2\) on the quoted errors and \(\nu_b\) its number of independent observables. Profiling \(s_b\) gives the same function, at \(\hat s_b^2 = \chi^2_b/\nu_b\) (the re-estimation of error bars of MacKay 1992). \(m\) does not change when any block's errors are multiplied by a constant, so its differences between models, such as the gap between two peaks, do not depend on how well the errors were quoted. Near a peak \(m \approx -\chi^2/(2\hat s^2)\), so its differences are those of the quoted-error log likelihood divided by \(\hat s^2\). Every block uses the Gaussian (small-\(\sigma\)) normalization, including uncorrelated closure phases, whose likelihood in model_loglike is a von Mises density with an improper unbounded marginal as \(s\to\infty\). \(m\) is a search surface, not a replacement for model_loglike. Where \(s\sigma\) is not small (weak closure phases with a large scale), s_max bounds each scale to \([1/s_\mathrm{max}, s_\mathrm{max}]\) and integrates it out numerically with the exact von Mises normalization: \(m=\sum_b\ln\int L_b(s)^{\mathrm{dof}}\,d\ln s\), adaptively in \(\ln s\), finite and proper where the unbounded marginal is not. The same bound keeps a flux-profiled score finite in score_orbits; rank_orbits has no flux to profile and defaults to s_max=None.
Data with gains or closure-phase offsets are scored with each affected block's covariance \(C(s) = s^2 D + UU^\top\), which a scale does not factor, so \(\ln s\) is integrated numerically: a 32-node Gauss–Legendre rule over a window around the integrand's peak (inside the Jeffreys range, s_max = 10 if none is given), each node whitened exactly with the log determinant of the gains. The V² amplitude (vis_amp) is refused for such data, because the gains supersede it; vis_amp=True then means none, logged at INFO. A tempering factor above 3, estimated on the gain-whitened residuals, warns that the noise model is inadequate. Extra observables with a model-dependent covariance are still refused.
Positions. epoch_positions fits each dataset by a static binary on a grid of positions and fluxes scored by \(m\). The n_peaks highest distinct local maxima more than gap_mas apart are each refined (with free, profiled vis_scale and phi_scale per dataset) and ranked by their refined \(m\), because fringe peaks are often narrower than the grid step and the best grid point is not always the best peak. The curvature of \(m\) at the best peak gives the covariance. Positions, covariances and gap_marginal therefore do not depend on how well the errors were quoted: a night with underestimated errors does not look more decisive than it is (the gap on the quoted errors grows as \(1/s^2\)). The grid step must be finer than the resolution, and fluxes are in (0, 1], since a binary with flux ratio \(f>1\) at \(r\) is the one with \(1/f\) at \(-r\). The positions are only a starting point for an orbit fit: with more than two point stars they can be biased.
One bad night. fit_orbit_aliases gives the nights one shared outlier rate \(\epsilon\) with the Beta(½, ½) (Jeffreys) prior and integrates it out: \(L=\int\prod_k[(1-\epsilon)L_k+\epsilon B_k]\,\pi(\epsilon)\,d\epsilon\) (group_outlier_mixture, a Gauss–Chebyshev rule that is exact for \(K\) nights, so the integral is exact; the mixture model itself is virgil's own design and was not chosen on merit). The outlier component \(B_k\) is set by outlier: "mixture", the night's mean likelihood over a companion anywhere in the prior's disc, with a log-uniform flux (broad_loglike; its extent is \(a_\max(1+e_\max)\), not a tuned box), scored as the orbit is; or "inflation", the night's own model with its noise scale log-uniform on \([1, s_\max]\). A night the orbit cannot reach, such as a sidelobe peak, then costs a bounded amount and cannot move the orbit; its posterior outlier probability is in AliasResult.outlier. There is one likelihood throughout: the search, the modes, the no-orbit null and the posterior. The default is "mixture", the nearest continuation of the earlier behaviour and not a choice on merit: running the no-orbit test on constructed data with each decides it. AliasResult.night_flags reports orbit-prefers-secondary: a night whose best peak lies more than \(3\sigma\) from the orbit's position while its surface at that position is within 10 nats of the peak (sidelobe_flags), reported, never used to exclude a night. outlier_eps and drop_outlier_night are ignored with a FutureWarning.
Starting an orbit fit. epoch_positions and the alias search take the nights' positions as seeds only when they are decisive (gap_marginal above min_gap) and unflagged; an ambiguous night's other peaks stay in positions.peaks, and only its visibilities judge between them. start_from_positions is superseded by fit_orbit_aliases and OrbitPipeline for orbits with an unknown period; it remains for starting a fit of a model of your own from per-night positions.
Tempering and the primary's diameter. The dof and block_dof arguments, which scale the differences of \(m\) for correlated errors, and primary_diam, which fits a resolved primary, are described with the alias search.
Scoring options
rank_orbits and start_from_positions integrate out each dataset's error scale (scales="marginal", the default), so a dataset with underestimated errors cannot dominate; pass scales="quoted" to rank on the quoted errors. score_orbits marginalizes the same way. Their models differ in shape: rank_orbits takes model(orbit) with the flux fixed, and score_orbits takes model(orbit, flux) and integrates the flux out. Both take the model before the data; score_orbits(epochs, model, ...), the order during 0.4.0 development, still works but warns, and is removed in 0.5.
Night flags
epoch_positions flags a night whose position should not seed an orbit (EpochPositions.flags, each with a code and a reason). The thresholds are keywords; None disables a flag.
| Code | Raised when | Keyword (default) |
|---|---|---|
alias-peaks |
another peak is within this many nats of the best | flag_alias_nats (2) |
low-gap |
gap_marginal is below this many nats |
flag_min_gap (5) |
sep-below-resolution |
the separation is below this fraction of the night's resolution \(\lambda/2B_{\max}\) | flag_sep_fraction (0.5) |
flux-at-bound |
the flux is within this fraction of a flux bound | flag_flux_tol (0.02) |
The two nat thresholds scale with the data volume, so retune them for very different data. sep-below-resolution is reported only unless flag_sep_blocks=True, because \(V^2\) and closure phases locate a companion below \(\lambda/2B\) at good signal to noise. For data with gains or closure-phase offsets the scale integral holds many whitenings per grid point: batch_size (or memory_budget, in bytes) sets the points scored together, and a coarse pass at one fixed scale per block integrates \(\ln s\) only within coarse_nats (30) of the best point and its coarse_margin (1) neighbours (EpochPositions.exact_fraction reports the share computed in full; coarse_nats=None integrates every point, which makes the result exact). The approximate scores outside that window feed gap_marginal and the choice of peaks to refine, so these two can change the peaks; batch_size and memory_budget never do.
A rival peak (alias-peaks) is a single-night alias, where the true position is often not the best peak. No threshold is a per-system number: the two nat thresholds are in the scale-marginalized score, and the other two are relative, to the night's own resolution and to a flux bound. A flux at the bound of 1 may be genuine for a near-equal pair; the flag says the labels are not determined. alias-peaks implies low-gap while flag_alias_nats <= flag_min_gap (the defaults), and only the more specific code is listed. A flagged night seeds nothing in fit_orbit_aliases, but its data still count in the likelihood. No flag catches nights whose errors are all underestimated alike, so read EpochPositions.chi2_raw too: epoch_positions warns about datasets whose raw \(\chi^2/N\) exceeds 4 (errors underestimated by more than 2), whose orbit fits need fitted error scales, and a rescaled \(\chi^2/N\approx1\) does not make them good fits.
Alias search
When the epochs are further apart than the period, more than one orbit count fits the positions. fit_orbit_aliases fits each alias band separately and weighs the bands by their evidence. This section explains its arguments and defaults; the docstrings give the calls. The decision tree is in Which orbit tool?.
Period window. Without p_range, period_window takes the window from the data alone, never from a published period, which would leak the answer into the fit; a fixed window is wrong for most data. The lower end is a Nyquist-style sampling limit. A night is treated as one snapshot, so the companion must not move more than a fraction (motion_fraction, half) of the resolution while it is observed. On a circular orbit of radius at most field it moves \(2\pi\,\mathrm{field}\,\mathrm{night}/P\) in a night, so \(P_\mathrm{min} = 2\pi\,\mathrm{field}\,\mathrm{night}/(0.5\,\lambda/B_\mathrm{max})\), and at least the night's length and 0.2 d (two stars in contact). field is the median separation of the unflagged night positions (one wrong alias peak at a large separation must not raise the limit), at most a_range[1], and the coarsest fringe spacing \(\lambda/B_\mathrm{min}\) without positions. night is the longest run of frames with no gap above half a day. The upper end is four times the span: a longer period is a short arc, of which less than a quarter of an orbit is seen. The window is logged at INFO. A lower end above five nights warns, as does a window with more than n_bands_max bands (default 200, each a set of fits), which also has its lower end raised (window_capped). AliasResult.period_bound is set when the best period is within 90% of the top of the window, or when σ(log P) spans a quarter of it (the period is unconstrained); period_at_lower_bound is set when it is within 10% of the bottom, where the sampling limit may have cut the truth.
Evidence. A band's log_z is the sum over its distinct fitted modes (both senses of motion; the \((\Omega+180°, \omega+180°)\) mirror is folded away by \(\Omega<180°\)) of the Laplace approximation to the marginal likelihood of the scale-marginalized likelihood, times the proper prior. A mode on a prior bound, such as a period edge between bands, uses its importance-sampling value instead, which truncates the target at the bound. The evidence misses modes the multistart does not find. log_z_is is the importance-sampling estimate from the deterministic mixture of the modes' Student-t proposals, and the posterior draws are resampled with the same weights. Each proposal's density wraps the angle differences (τ, ω, Ω) to the nearest period image, so draws from one mode are scored correctly by another; each mode's draws stay within half a period of it, so when modes straddle the Ω fold log_z_is and the draws can be slightly biased; log_z is unaffected except near prior bounds. Without s_max the Jeffreys prior on each error scale is improper, so the absolute log_z is defined only up to a constant shared by all bands: p and differences are meaningful.
Optimizer. Each start is optimized by damped Newton (Levenberg–Marquardt) steps on the scale-marginalized log likelihood. The curvature is that of iteratively reweighted least squares: each observable block's residuals are weighted by the slope of the log likelihood in its χ² (for s_max=None, \(1/\hat s^2\) with \(\hat s^2=\chi^2/\nu\)), and the profiled V² amplitude is differentiated through. A step is kept only if the log likelihood rises, so the curvature sets the speed, not the optimum. A start that does not converge in max_steps is continued by L-BFGS-B and polished by Newton steps. A band that raises is kept as a band-failed row with log_z = -inf and the others are unaffected, unless all fail. The likelihood and its gradient are evaluated once at the centre of the first band before any fitting, so misconfiguration raises at once.
Flags. flags lists why a band should not be trusted: near-prior-bound, not-converged (more than 0.1σ from a stationary point), hessian-not-positive-definite, hessian-singular, band-failed, starts-failed, laplace-is-differ (Laplace and importance-sampling evidences differ by more than flag_nats), low-ess (the best mode's ESS is below ess_min), no-valid-mode and poor-fit. chi2_red is the raw χ²/ν on the quoted errors at the best mode. poor-fit is set on the winning band only, with a warning, when chi2_red exceeds 10: the fits missed the orbit, or the errors are underestimated by more than 3 times (the per-epoch error scales absorb less).
Seeds and flagged nights. With positions, each band's fits start from Thiele–Innes grids on the per-night positions and, by default, beside them the grids that also fit the nights' velocities (arc_profile; the position grids alone are position_profile, as with short_arcs=False: the arcs only add seeds, so a band they keep still has every position seed), and only the bands that the short arcs admit are fitted (below). A night that epoch_positions flagged (a single-night alias peak, a low gap, a χ²/N far above the median night, a flux at its bound) seeds nothing, but its data still count in the likelihood of every band (skip_flagged=True); the skipped nights are in AliasResult.unseeded. Few seeding nights mean loosely determined positions, and one wrong night misleads them all, so with n_random=None there are 1000 random candidates without positions, 200 beside positions from three or fewer seeding nights, and none beside more. When fewer than two nights can seed, the positions are dropped with a warning and at least 200 random candidates are used.
Label swap. A companion nearly as bright as the primary leaves each night's position known only up to a point reflection, which swaps the stars' labels (\(\omega+180°\)). With sign_free=True (the default) the seeds add sign-free Thiele–Innes orbits to the signed ones, and keep the signed ones because the closure phases do fix the signs for a contrast pair; a sign-free fit alone would crowd the true orbit out with mixed-sign orbits. Flux seeds near flux_range[1] are tried as well. A band is marked labels_free when its best mode has a point-reflected partner whose evidence is within LABELS_FREE_NATS (3 nats: odds of 1 to 20, Δχ² of about 6) and whose track agrees to within a quarter of \(\lambda/B_\mathrm{max}\): the data cannot say which star is which, and a comparison with another orbit is then meaningful only up to the reflection. This costs twice the seed orbits and half as many fluxes again.
Flux flip. A companion brighter than the primary has a flux ratio above the prior's top. With flip_flux=True a mode within 0.02 of the top in log flux is refit with the labels swapped (\(\omega+180°\), flux to \(1/\mathrm{flux}\)) and the better result is kept, with flipped set on the band if it won. This applies to a point primary without differential phases only, because otherwise the swap is not a relabelling.
Resolved primary. A resolved primary makes a point-star model fit badly, and the misfit leaks into the companion's flux and position. epoch_positions(primary_diam=) fits beside a uniform-disk primary of fixed diameter. With primary_diam="auto", a cheap first pass (estimate_primary_diameter) re-refines each night from its position at each diameter of a grid (0 and 0.03 to 1.3 of the finest fringe spacing \(\lambda/B_\mathrm{max}\)) on \(m\), with the same per-night V² amplitude as the fit, sums the nights' scores (the diameter is shared; flagged nights are left out unless every night is flagged), and takes the best by a parabola through its two neighbours, whose curvature gives sigma. The primary counts as resolved when the best diameter is positive and its summed score exceeds the point primary's by resolve_nats (5 nats: one extra parameter, \(\Delta\chi^2\approx10\), about 3\(\sigma\)), on the tempered score. If so, the engine fits the diameter (as "fit", with a lower bound effectively 0 starting from the estimate) and the seeds are the positions re-refined with it, so that seeds and engine share one primary; the estimate is in AliasResult.primary_fit. The first pass costs a few dozen small per-night fits, and its static snapshot ignores motion within a night, as the seeds do. It uses no published value; give a fixed diameter from the data or a calibrator, never from the orbit being tested. Without EpochPositions there is nothing to estimate from: it warns and uses a point primary. EpochPositions refined at a fixed diameter that the data do not resolve are kept with a warning and the fit uses a point. A \(V^2\) contrast loss that is the same on every baseline is partly degenerate with a small disk here; vis_amp (below) profiles a per-night amplitude to separate them, and the orbit fit's own amplitude refits the diameter. diam_range defaults to (0.05, 5) mas for "fit", and for "auto" to 0.001 to 1.5 times \(\lambda/B_\mathrm{max}\) (at least twice the estimate), so it follows the data; 1e-3 mas changes V² by less than 1e-9.
V² amplitude. A contrast loss that is the same on every baseline and wavelength, unlike a resolved primary, is a per-night multiplicative amplitude \(A\) on the squared visibilities, profiled analytically (the best \(A\), clipped to a range that only bounds it). No prior or Occam factor for \(A\) enters log_z, which is then a profile in \(A\); every band has the same number of amplitudes, so bands compare. vis_amp=True uses the range (0.5, 1.2) when every dataset has squared visibilities and none otherwise; an explicit range always fits and raises for data without them. The amplitudes are reported per epoch, and the epoch's error scale is kept.
Tempering. Errors correlated beyond the model of the quoted errors, such as correlated spectral channels, carry fewer than \(\nu_b\) degrees of freedom, and \(m\) and the evidence are then overconfident by about \(\nu_b/\nu_\mathrm{eff}\) (band probabilities of 1.000 at \(\chi^2/N\) of 12, and posteriors far too narrow). dof (a fraction of \(\nu_b\), one number or a dict keyed by dataset) or block_dof ({block: 1/f_b}, as AliasResult.block_dof() gives) scales every difference of \(m\) down by that factor, and cov up by \(1/\mathrm{dof}\). With temper=True (opt-in until 0.5; the default is False) fit_orbit_aliases estimates the factor \(f_b\ge1\) of each block from the residuals of each night's best static fit (this needs EpochPositions; one wavelength gives 1) and divides the block's log likelihood (virgil.tempering). False is untempered, and a float is a fixed factor, which also tempers the "auto" primary test. The result records f (temper_f, temper_blocks, temper_rho) and sets tempering, with a warning, for a block f above 2, a raw f below 0.5 or a flat correlation. LABELS_FREE_NATS and RESOLVE_NATS are in tempered nats, so they are compared with untempered differences when temper=False (the default): on correlated channels the "auto" primary test then calls a disc resolved, and the labels decided, more readily than the tempered thresholds intend. With white noise or a single channel they are unchanged.
Saved results. AliasResult.save writes JSON with a format field (1). load accepts a file without the field, a legacy file, in which the primary's diameter and the V² amplitude settings may be missing: the accessors scene, residuals and chi2_per_night then refuse to guess a point primary or no amplitude, and load(path, primary_diam=..., vis_amp=...) supplies them. It refuses a file whose format is newer than the installed virgil's.
Short arcs
Nights months apart leave one band for every whole number of cycles between them, and the window can hold a hundred or more. The motion seen over short arcs, within a night and between nights a few days apart, rules most of them out before any band is fitted. This is the step short_arcs=True (the default) adds, with EpochPositions and skip_flagged=True: a night whose position may be point-reflected (a label swap, or an alias peak) is flagged, and the signed fits below need every seeding night's sign. An unflagged night's sign counts as decided when its gap_marginal (its best peak over every rival, its point reflection among them) is at least arc_min_gap, 5 nats by default, after tempering when temper=True: gap_marginal comes from a surface that treats the channels as independent, so it is divided by the effective-channel factor \(f\) (the largest of the blocks' factors, the tempering above), as the evidence is, and the positions' and velocities' covariances are multiplied by it. With correlated channels a night's best peak can be decisive by tens of nats untempered, and be a fringe alias; cutting bands on it would lose the true cycle count. With temper=False (the default) no factor is estimated, the gate sees the untempered gaps and can cut the true band on correlated channels; use temper=True for such data. A near-equal pair's reflections tie, and a night that is not decisive once tempered leaves the cut off; its positions, like any others, then seed every band, as before.
Velocities. The window's lower end already assumes the period is sampled within a night (above). night_motion splits each night's frames into an earlier and a later half, refines each half's position from the night's on the same scale-marginalized surface, and takes the difference over the time between them as the night's velocity, with the halves' covariances and each half's arc_jitter floor (below), since the halves see different uv coverage and their biases need not cancel. A night with one frame, or whose halves move to another peak (more than half of \(\lambda/B_\mathrm{max}\)), has none. Positions and velocities are both linear in the Thiele–Innes constants at a fixed period, time of periastron and eccentricity, so one least-squares fit uses both.
Unwrapping. unwrap_cycles joins the nights shortest gap first. At each step whose arc has more measured coordinates than the seven orbit parameters, every period still admitted (on a grid that stays within 1/9 of a cycle over the arc) is scored by its best fit over the eccentricity (0 to ecc_max), the time of periastron and the four constants, which span every inclination, orientation and size. The best point of each period's grid is polished by a local search, because a coarse grid only bounds a period's best χ² from above. So the bounds hold for any eccentricity and inclination, with no Kepler's-law guess at the mass or distance. A period is kept while its χ² is within arc_delta_chi2 (25, 5σ in one parameter) of the best, scaled by the best fit's χ²/dof when that is above 1. The admitted periods are intersected step by step, so a long gap admits only the cycle counts that the shorter arcs allow. Each night's position error has a floor of arc_jitter (0.1) of \(\lambda/B_\mathrm{max}\) added in quadrature, because a night's position can be biased by a fraction of the resolution, and one tight night must not cut the true period. Too few data leave the whole window.
A cheap check. A band the arcs exclude is still scored, cheaply: the full likelihood at its best three unrefined seeds. If that beats the best of every admitted band, it is fitted after all, with a warning. Weak or misleading arcs therefore fit more bands, never fewer. The band probabilities p are then conditional on the bands fitted, not a posterior over the whole window. AliasResult.short_arc records the admitted periods, the bands kept, excluded and readmitted, each band's cheap-check log likelihood (seed_scores, to see how much was cut), the velocities and each unwrapping step.
Alias-search settings
The defaults of fit_orbit_aliases need no per-system arguments; the knobs below are for tuning effort and diagnostics.
- Effort per band:
n_candidates,n_refine,n_random,min_distance_mas(distinct modes),max_steps;n_isimportance-sampling draws check each Laplace evidence (flag_natsis thelaplace-is-differthreshold andess_minthelow-essone);n_samplesposterior draws are taken in the winning band and in every band with probability abovep_min_samples. - Primary:
primary_diam="auto"fits a shared uniform-disk diameter to the per-night positions and, when the data resolve it (a gain of 5 nats over a point), lets the engine fit it indiam_range, by default 0.001 mas to the larger of \(1.5\,\lambda/B_{\max}\) and twice the estimate;"fit"samples it indiam_range, by default (0.05, 5) mas. Either way the prior is log-uniform. - Short arcs:
short_arcs=Truefits only the bands whose cycle counts the short arcs admit (virgil.arcs).arc_jitteris a position floor in units of \(\lambda/B_{\max}\),arc_delta_chi2the \(\chi^2\) margin around the best period, andarc_min_gapthe temperedgap_marginal / f(nats) a night needs for its sign to count as decided; the cut's position and velocity errors are tempered by \(f\) too. It needsEpochPositionsandskip_flagged; otherwise every band is seeded from the positions. - Window and tempering:
n_bands_maxcaps the bands of a defaultp_range(a longer window is cut, with a warning);temperis opt-in (defaultFalse), a fixed factor, orTrueto estimate it. - Memory:
batch_sizeandmemory_budgetchange speed, never the result.
Radial-velocity likelihood terms
RVData.term returns a likelihood term for the likelihoods= argument of fit.
Jitter. jitter= names a fitted value holding an RV jitter \(s\) (km/s), which inflates the errors to \(\sqrt{d_{\rm rv}^2 + s^2}\). The normalization \(\sum \log \sigma_{\rm eff}\) then depends on a parameter, so the term reports it as log_norm, fit adds it to the loss, and the default solver is L-BFGS (there is no least-squares form). Give the jitter a prior with positive support. The jitter is a scale, so the default is dist.LogUniform(lo, hi) (the Jeffreys prior); pick lo well below the smallest plausible scatter and hi above the largest. dist.HalfNormal is a deliberate informative choice (a scale about the expected scatter, a few km/s for a spotted star). The likelihood depends on \(s^2\) only.
Marginalized zero points. marginalize_offsets=(mean, sd) analytically marginalizes one velocity zero point per instrument (Luger, Foreman-Mackey & Hogg 2017, arXiv:1710.11136). The model is \(m_{\rm kepler} + A w\), with \(A\) the indicator matrix of the instruments and \(w_j \sim N(\mathrm{mean}_j, \mathrm{sd}_j^2)\). One zero point per instrument, with no separate \(\gamma\), avoids a degeneracy: \(w_j\) is the systemic velocity as measured by instrument \(j\), and offsets are the differences \(w_j - w_0\). Return gamma = 0 from params (a nonzero value just shifts the prior mean). mean and sd are scalars or one per instrument, in the order of RVData.instruments, in km/s; True is an error, because the prior must be stated.
The density is the dense \(N(m + A\mu,\ C + A \Lambda A^\top)\) log density with \(C = \mathrm{diag}(\sigma_{\rm eff}^2)\), evaluated by the Woodbury identity and the matrix-determinant lemma in \(O(Nk^2)\), so the jitter enters the full log-determinant. For a broad prior this is the profile likelihood plus a log-determinant correction; a flat prior is the \(\Lambda \to \infty\) limit up to a \(\Lambda\)-dependent constant, and only finite sd is supported. The term's residuals have length \(N\) and its log_norm carries the marginal log-determinant. term.posterior(values) returns the zero points' conditional mean and covariance, to report after a fit.
Implementation notes and references
jaxoplanet (an optional dependency, pip install "virgil-astro[orbits]") solves Kepler's equation with exact derivatives, and the positions follow from the Thiele–Innes constants. jaxoplanet's own conventions differ (its \(\omega\) is the primary's and its third axis points toward the observer); they stay inside KeplerOrbit.to_jaxoplanet and KeplerOrbit.from_jaxoplanet.
The Kepler solver is jaxoplanet (Hattori et al., Zenodo, doi:10.5281/zenodo.10736936), which descends from exoplanet (Foreman-Mackey et al. 2021, JOSS 6, 3285). The linear Thiele–Innes fit at fixed \((P, e, T)\) is the classical method (Thiele 1883, Astron. Nachr. 104, 245), as used for visual binaries by Hartkopf, McAlister & Franz (1989, AJ 98, 1014), by Wright & Howard (2009, ApJS 182, 205) for linear parameters and by Lucy (2014, A&A 563, A126) for incomplete orbits, whose dense grid in \((P, e, T)\) with a linear solve starting_orbits follows. The frequency spacing of the period grid is that of a periodogram, as in Lucy (2014) and The Joker (Price-Whelan et al. 2017, ApJ 837, 20). The position angle at a reference epoch and the fits to closure phases follow Octofitter (Thompson et al. 2023, AJ 166, 164). No code is taken from these packages.