Skip to content

virgil.orbit_cells

The period domain, the cells, the mode search and the position-level evidence of the alias-resolved orbit fit: every cell of the period prior is searched for the modes of the night-summary likelihood (minimal sets of nights, variable projection, C-steps), and its evidence is a defensive importance-sampling estimate from those modes and the images of the target's symmetries; the posterior draws are an HMC resample-move.

Cells, period domain and the position-level search of the alias-resolved orbit fit.

Provisional

May change in any 0.4.x release without a deprecation cycle.

The period prior is log-uniform on [P_cut, P_max] (period_domain). Two anchor nights set T, and T / P = N + ρ splits the domain into cells, an exact partition for any edges (make_cells). Each cell is searched for the modes of the night-summary likelihood of virgil.night_summaries, in the (ln P, z, ζ) coordinates of virgil._orbit_coordinates: variable projection of the Thiele–Innes constants on minimal sets of nights, concentration steps and Newton refinement. A defensive mixture on the modes (with the images of the exact symmetries of the target) gives the evidence by importance sampling, and an HMC resample-move gives posterior draws (position_leg). The generic parts are in virgil.mode_search. position_cells runs every cell and gives p(N) ∝ prior mass × Ẑ_N, with an opt-in pruning that records the dropped mass; a cell whose search missed the dominant mode (cell-at-floor) is a failure, never an evidence.

Source: Fischler & Bolles (1981), Rousseeuw (1984), Rousseeuw & Van Driessen (1999), Golub & Pereyra (1973), Hesterberg (1995), Gilks & Berzuini (2001), references; the cells, outlier floor and search are derived in the design note.

PeriodDomain dataclass

The period prior log-uniform [p_cut, p_max] (days), declared.

Attributes:

Name Type Description
overridden bool

True when p_range replaced the derived limits.

binding {'2dt_min', p_floor, p_range}

The term that sets p_cut.

a_hi, span, sigma_min float

The inputs of p_max = 2π a_hi span / sigma_min (mas, days, mas); sigma_min is nan without a night with a peak.

n0_mass float

Prior mass of the long-period band N = 0 (P > span).

p_cut instance-attribute

p_max instance-attribute

overridden instance-attribute

binding = 'p_range' class-attribute instance-attribute

a_hi = math.nan class-attribute instance-attribute

span = math.nan class-attribute instance-attribute

sigma_min = math.nan class-attribute instance-attribute

n0_mass = math.nan class-attribute instance-attribute

__init__(p_cut, p_max, overridden, binding='p_range', a_hi=math.nan, span=math.nan, sigma_min=math.nan, n0_mass=math.nan)

Cell dataclass

One cell: p_lo <= P <= p_hi (days), N = round(T / P).

log_mass is the cell's share of the period prior, ln[ln(p_hi / p_lo) / ln(P_max / P_cut)] (the period prior is log-uniform). Cell N = 0 is the long-period band (P > T, no cycle count), which ends at P_max.

n instance-attribute

p_lo instance-attribute

p_hi instance-attribute

log_mass instance-attribute

__init__(n, p_lo, p_hi, log_mass)

OutlierPrior dataclass

The tabulated joint prior predictive of a night state (design §2.2).

samples are (ln|p|, ln|v|, ψ) of prior draws (ψ the angle between v and p), bandwidth the Scott bandwidths and ln_f_floor the lower end of the flux prior.

samples instance-attribute

bandwidth instance-attribute

ln_f_floor instance-attribute

__init__(samples, bandwidth, ln_f_floor)

log_density(mean, velocity=True, sigma_f=None)

ln π(p, v) π(f) at mean = (dra, ddec, vra, vdec, ln f), a density in (p, v, ln f); -inf outside the flux range. With velocity=False the velocity is integrated out: the density in (p, ln f) (mean[2:4] unused). With sigma_f the flux box is integrated over a Gaussian ln f error of that width (:meth:log_flux_box) instead of evaluated at mean[:, 4].

log_flux_box(m_f, sigma_f)

ln E[π(ln f)] for ln f ~ N(m_f, σ_f²): the uniform flux prior on [ℓ, 0] (ℓ = ln_f_floor) integrated over the Gaussian measurement error, [Φ(-m/σ) - Φ((ℓ-m)/σ)] / |ℓ|. Finite for every m_f, including m_f > 0.

CellFit dataclass

The position-level fit of one cell (search, importance sampling, draws).

Attributes:

Name Type Description
cell Cell
log_z, log_z_error float

ln Ẑ_N^pos of the cell's normalized prior (the cell's mass is applied in CellsResult) and its delta-method error √(1/ESS - 1/n).

modes list of Mode
draws array or None

Resample-move posterior draws (chart vectors); None until made.

log_w, x_is array

The importance draws and their log weights (exact, not resampled).

at_floor bool

cell-at-floor: the draws sit at the all-outlier floor although the search found a mode above it, so the search missed the dominant mode. Never report the cell's log_z as an evidence. It fails the system only if the cell could matter: see CellsResult.failed.

undersampled bool

cell-undersampled: the ESS is below ESS_TARGET; information only.

unreliable bool

The ESS is below ESS_FAIL: the estimate is a few draws and its error meaningless (a search that found only a partial-outlier mode had ESS about 1 and an evidence 100 nats low). It fails the system only if the cell could matter: see CellsResult.failed. The error log_z_error is a lower bound (first order in 1/ESS) and is not propagated into p_pos.

nonfinite bool

Some importance draws had a non-finite target: the cell failed.

search_evaluations, is_evaluations int

Likelihood-equivalent evaluations of the search and the sampling.

move Move or None

The resample-move of draws (HMC acceptance and step size).

shared list of Mode

Neighbour modes that straddle a shared edge, in this cell's chart: extra components of the mixture (not in modes).

info dict

The search's counts (c_capped, c_runs, ...: search_cell).

log_l_sup float

The largest ln L evaluated in the cell (at every found mode and importance draw): a lower bound on the cell's sup ln L, which itself bounds ln Z_N (the cell prior is normalized). It is a bound on Z_N only if the search found the cell's top mode (design §6.10); nan (not set) counts as mattering.

cell instance-attribute

log_z instance-attribute

log_z_error instance-attribute

modes instance-attribute

draws instance-attribute

log_w instance-attribute

x_is instance-attribute

at_floor instance-attribute

undersampled instance-attribute

search_evaluations instance-attribute

is_evaluations instance-attribute

evidence = dataclasses.field(repr=False, default=None) class-attribute instance-attribute

plan = dataclasses.field(repr=False, default=None) class-attribute instance-attribute

space = dataclasses.field(repr=False, default=None) class-attribute instance-attribute

unreliable = False class-attribute instance-attribute

nonfinite = False class-attribute instance-attribute

move = dataclasses.field(repr=False, default=None) class-attribute instance-attribute

shared = dataclasses.field(repr=False, default_factory=list) class-attribute instance-attribute

info = dataclasses.field(repr=False, default_factory=dict) class-attribute instance-attribute

log_l_sup = float('nan') class-attribute instance-attribute

failed property

The cell failed on its own: at_floor or nonfinite.

__init__(cell, log_z, log_z_error, modes, draws, log_w, x_is, at_floor, undersampled, search_evaluations, is_evaluations, evidence=None, plan=None, space=None, unreliable=False, nonfinite=False, move=None, shared=list(), info=dict(), log_l_sup=float('nan'))

CellsResult dataclass

The position-level fit over every cell.

Attributes:

Name Type Description
domain PeriodDomain
anchors (int, int)

Indices of the anchor nights.

t_ab float

T, the time between the anchors (days).

cells list of Cell
fits list of CellFit
p_pos ndarray

p(N) ∝ mass_N Ẑ_N^pos over the cells, summing to one; all nan when a cell failed (never renormalized over the others).

below_delta ndarray

Cells with p_pos < δ / N_cells: the ones pruning would drop.

pruned ndarray

Cells actually dropped (all false unless prune=True).

pruned_mass float

Σ p_pos over below_delta (< δ by construction): the position-level mass pruning drops, for Stage 4 to compare with the visibility level.

jitter float

The position jitter used (mas).

failed ndarray

Cells with a non-finite target, or at the floor (cell-at-floor: the search missed the dominant mode) or unreliable (ESS below ESS_FAIL) and it matters (below). A flagged cell that cannot matter is information only: it stays flagged on its fit (CellFit.at_floor, unreliable) but does not fail the system. Any true entry makes p_pos undefined.

upper, matters ndarray

upper = ln mass + ln sup L bounds the cell's ln (mass Z_N). With R the best ln mass + ln Ẑ among unflagged cells, a cell matters iff it has no found mode or upper >= R - ln(n_cells/δ) (every flagged cell matters if none is unflagged).

omitted_bound float

The summed exp(upper) of flagged cells that do not matter, over the total mass. A diagnostic: below δ by the threshold, given the search found each cell's top mode (a lower sup L would understate it).

domain instance-attribute

anchors instance-attribute

t_ab instance-attribute

cells instance-attribute

fits instance-attribute

p_pos instance-attribute

below_delta instance-attribute

pruned instance-attribute

pruned_mass instance-attribute

jitter instance-attribute

failed instance-attribute

upper = None class-attribute instance-attribute

matters = None class-attribute instance-attribute

omitted_bound = None class-attribute instance-attribute

__init__(domain, anchors, t_ab, cells, fits, p_pos, below_delta, pruned, pruned_mass, jitter, failed, upper=None, matters=None, omitted_bound=None)

period_domain(summaries, *, a_range=A_RANGE, p_range=None, gap_days=GAP_DAYS, p_floor=_P_FLOOR)

The declared period domain [P_cut, P_max] (design §1.3).

P_cut = max(2 Δt_min, p_floor), Δt_min the shortest gap between consecutive nights after merging nights less than gap_days apart: above it the closest pair of nights advances by under half a cycle, so the regular-sampling alias lies outside the domain. There is no within-night bound; the per-exposure target and the exact-projection summaries model the motion within a night. A prior choice, not a Nyquist limit. P_max = 2π a_hi · span / σ_min, with σ_min the smallest night position error: beyond it the motion over the span is below that error.

Parameters:

Name Type Description Default
summaries sequence of NightSummary

One per night.

required
a_range (float, float)

Prior range of the semimajor axis (mas); a_hi is the field.

A_RANGE
p_range (float, float)

Override (P_cut, P_max).

None
gap_days float

Nights closer than this merge (default 0.5 d, as OIData.epochs).

GAP_DAYS
p_floor float

The only other lower bound (days).

_P_FLOOR

Returns:

Type Description
PeriodDomain

With the binding term of P_cut, the inputs of P_max and the prior mass of the N = 0 band.

choose_anchors(summaries)

Indices (first, last) of the two anchor nights.

The night with the smallest best-peak position error among those in the first quarter of the span, and likewise in the last; an empty quarter falls back to the first (last) night with a peak, and if both choices are one night, to the earliest and latest nights with a peak. They always differ.

make_cells(t_a, t_b, domain, p_edges=None)

The cells of domain for anchors at t_a and t_b (days).

The default edges are those of alias_bands (T / P half-integers). p_edges replace them: one period between each pair of consecutive cells, increasing with N decreasing.

Returns:

Type Description
list of Cell

Ordered by N; their masses sum to one.

outlier_prior(domain, a_range=A_RANGE, e_max=E_MAX, flux_floor=FLUX_FLOOR, n=2 ** 20, seed=0)

Tabulate the prior predictive of (p, v) at a random epoch.

n scrambled-Sobol draws of the orbit prior (log-uniform P on the domain and a, uniform e and M, isotropic orientation) are mapped to (ln|p|, ln|v|, ψ); the density is a Gaussian KDE with Scott's bandwidth, smooth for the night cubature.

Returns:

Type Description
OutlierPrior

outlier_log_density(summaries, prior, s_max=S_MAX)

Each night's log outlier density b_k (Laplace form, design §2.3).

b_k = ln Σ_peaks L_j (2π)^{5/2} |Σ_j|^{1/2} π_out(m_j) with each peak's own error scales integrated (log-uniform on [1/s_max, s_max], by Laplace; fixed at 1 for a peak that is not rescalable). On a single-exposure night the velocity is integrated out of π_out, leaving the (p, ln f) Laplace form. A night without a peak gets its no-companion likelihood.

Parameters:

Name Type Description Default
summaries sequence of NightSummary
required
prior OutlierPrior
required
s_max float

Bound of the scale prior (default 10).

S_MAX

Returns:

Type Description
ndarray

b_k, on the normalization of NightPeak.loglike.

search_plan(space, key=None, nu_width=None)

The minimal sets of a system, as arrays (the same for every cell).

Pairs of nights (positions and velocities: 8 equations for the 4 TI′ at fixed (P, ζ)) and triplets (positions only: 6), with every combination of their peaks. Above N_SET_MAX sets the triplets are the random interior fills of every pair (per pair of nights (a, b) with a night between them, ⌈ln δ / ln(1 - w)⌉ triplets (a, c, b), c an interior night with a peak, the three peaks random; design §6.1; drawn from key) and the pairs stay whole, so the pair that spans the inliers (it pins the period to σ / (a Δ)) is always there.

The ln P grid has ⌈K_COH Δ ν_w⌉ + 1 nodes (at least K_COH + 1) equally spaced in ν = 1 / P over a cell, Δ the largest set span and ν_w the largest cell width in ν (1 / T; default the width of space.cell): at least K_COH per cycle of the widest set.

Each set carries its precisions W (the (p, v) block of the peak's total covariance at ln s = 0 and the fitted jitter), the peak means, the precision-weighted ln f and the cut on its residual: the 1 - δ quantile of χ² with the set's equations less the 4 TI′, times S_MAX² where the error scale is free ((P, ζ) are fitted too, which only lowers the residual: the cut is conservative). It applies to the data residual Σ rᵀ W r at the ridge solution, not to the ridge-penalized R: the ridge term |TI′|²/s_w² grows with the orbit (the old cut removed every true set at a = 25 mas). The ridge solution's data residual exceeds the least-squares one by at most |TI′|² / (4 s_w²) (per eigendirection λ² d / (d + λ)² is at most λ / 4), negligible once the sets are informative (σ well below s_w).

search_cell(space, key=None, *, plan=None, info=None)

The modes of the label-summed target in one cell, best first.

  1. Every minimal set of search_plan, at each of the 17 ζ starts, on a ln P grid of the cell; at every grid minimum a damped Newton in (ln P, ζ) on the set's variable-projection residual.
  2. Candidates whose set residual exceeds its derived χ² cut are dropped, the rest deduplicated by labels and (ln P, ζ).
  3. C-steps (at most N_C): Newton on the labelled target in the full chart, relabel, until the labels repeat.
  4. Add-one: each outlier night with a peak tried as an inlier (C-steps and Newton), kept while the label-summed objective rises.
  5. Newton on the label-summed objective; the covariance is the inverse of its saddle-free Hessian (|eigenvalues|); distinct_modes.

info, a dict, receives the counts of each step, the runs ended by the step cap in each of the VarPro, pre-pass and C-step stages (varpro_capped of varpro_runs, pre_capped of pre_runs, c_capped of c_runs; only the C-steps are meant to converge) and evaluations, the likelihood-equivalent cost (a gradient is 3, a Hessian 3 per dimension).

Source: Fischler & Bolles (1981), Rousseeuw (1984), Rousseeuw & Van Driessen (1999), Hadi & Simonoff (1993), Golub & Pereyra (1973).

position_leg(summaries, log_outlier, cell, key, *, t_anchor, t_nights, a_range=A_RANGE, e_max=E_MAX, flux_floor=FLUX_FLOOR, jitter=0.0, jitter_ref=None, jitter_range=JITTER_RANGE, n_is=N_IS, posterior_draws=True, dtype='float64', plan=None, nu_width=None, shared=())

Search, defensive importance sampling and posterior draws of one cell.

The modes of the cell (search_cell) with the images of the target's symmetries are the components of a defensive mixture; ln Ẑ is its importance-sampling estimate and the draws come from an HMC resample-move of the weighted draws.

Parameters:

Name Type Description Default
summaries sequence of NightSummary

The nights.

required
log_outlier array - like

Each night's b_k (from outlier_log_density).

required
cell Cell
required
key PRNGKey
required
t_anchor (float, array - like)

The anchor time and each night's reference time (days, any common origin).

required
t_nights (float, array - like)

The anchor time and each night's reference time (days, any common origin).

required
a_range declared prior bounds

Semimajor axis (mas), maximum eccentricity and flux-ratio floor.

A_RANGE
e_max declared prior bounds

Semimajor axis (mas), maximum eccentricity and flux-ratio floor.

A_RANGE
flux_floor declared prior bounds

Semimajor axis (mas), maximum eccentricity and flux-ratio floor.

A_RANGE
jitter float or None

A fixed position jitter (mas) added in quadrature (default 0), or None to marginalize it: σ_J is then a coordinate of the chart, log-uniform on JITTER_RANGE, with the same inlier likelihood for every night (the outlier floor b_k is its own integral over the night's scale, free of σ_J), so a night with modest excess scatter is absorbed by σ_J instead of labelled an outlier.

0.0
jitter_ref float

With jitter=None, the reference σ_J (mas) the search runs at and the chart starts from (default the median quoted position error; reference_jitter is better).

None
jitter_range (float, float)

With jitter=None, the σ_J prior bounds (mas, default JITTER_RANGE): widen the ceiling for large separations.

JITTER_RANGE
n_is int

Importance draws.

N_IS
posterior_draws bool

Make the resample-move draws (not for a cell that failed).

True
dtype (float64, float32)

Precision of the run (default float64, as fit).

"float64"
plan dict

The sets of search_plan, reused across the cells of a system.

None
nu_width float

The widest cell in 1 / P (1 / T), to size the plan's ln P grid when plan is made here (default the width of cell).

None
shared sequence of Mode

Neighbour modes in this cell's chart, extra mixture components (position_cells makes them).

()

Returns:

Name Type Description
CellFit
Source Hesterberg (1995), Gilks & Berzuini (2001), Hoffman & Gelman (2014).

decode_particles(result)

Orbit coordinates of a fit's posterior draws.

Returns a dict of arrays with period, z, zeta, ln_f, ln_s, jitter (σ_J, mas) and the reporting invariants a, ecc, cos_inc, omega and Omega (invariant under the covers of z and ζ).

jitter_draws(fits, p)

(σ_J, weight) of the cells' importance draws, the weights summing to one and carrying p(N); None where p is undefined (a failed fit) or there are no usable draws (a cell with no finite weight is skipped).

jitter_quantile(draws, q)

Weighted quantile q of jitter_draws.

fit_chi2(fit, mode=None)

Raw χ²/N of a mode's inlier nights on the quoted and the total errors.

Both are on the nights' best peaks as (p, v) measurements ((p) on a single-frame night): quoted with the quoted covariance (scale 1, no jitter), total with σ² + σ_J² (the brighter or fainter label chosen by sign_log_likelihood); n is the number of data and n_inliers the nights. Neither is rescaled: a quoted far above 1 with total near 1 is jitter, total far above 1 is a failed fit. Nights are the mode's labels (_labels).

Parameters:

Name Type Description Default
fit CellFit
required
mode Mode

Default the cell's highest-evidence mode.

None

Returns:

Type Description
dict

quoted, total (nan with no inlier night), n, n_inliers and jitter (mas).

reference_jitter(summaries, domain, t_ab, *, n_best=3, jitter_range=JITTER_RANGE)

A robust reference σ_J (mas) for the search; never the fitted value.

The search (plan covariances, C-steps) runs at one fixed jitter, so it needs a starting scale: the excess of the nights' position scatter about the best position-only seed orbits (position_profile, best peaks as positions) over the quoted errors, by medians (outlier nights do not move them): σ_J² = max(median(|r|² / 2) / ln 2 - median(σ²), 0), the least over the seeds, clipped to JITTER_RANGE. The posterior of σ_J is the chart's own last coordinate (position_leg with jitter=None); this value only places the search and starts that coordinate, and the modes' Newton moves it.

Parameters:

Name Type Description Default
summaries sequence of NightSummary
required
domain PeriodDomain
required
t_ab (float, float)

The anchor times (days).

required
n_best int

Seed orbits per cell (budget, 3).

3
jitter_range (float, float)

The σ_J bounds the result is clipped to (default JITTER_RANGE).

JITTER_RANGE

Returns:

Type Description
float

position_cells(summaries, domain, key, *, log_outlier=None, outlier=None, jitter=None, prune=False, delta=DELTA, n_is=N_IS, max_seconds=float('inf'), workers=N_WORKERS, **leg_kwargs)

The position-level fit of every cell of domain.

Chooses the anchors, makes the cells (edges at the half-integers of T / P: edges change labels only) and runs the search and the importance sampling in each; p(N) ∝ mass_N Ẑ_N. Resample-move draws are made only where p(N) >= δ / N_cells. The cells are independent, so a system compiles once and the sets are drawn once.

TODO: share one search and one set of importance draws across the cells (exact, unbiased for every N at once; design §6.7). Not implemented: it is unmeasured (scripts/leg1_toys/alias_grid.py has not run).

Parameters:

Name Type Description Default
summaries sequence of NightSummary required
domain PeriodDomain
required
key PRNGKey
required
log_outlier array - like

Each night's b_k; default computed from outlier.

None
outlier OutlierPrior

The prior predictive for b_k (default tabulated for domain).

None
jitter float

A fixed position jitter (mas), 0 for none. Default None: marginalized over JITTER_RANGE in every cell (position_leg), the search starting from reference_jitter. CellsResult.jitter is then the posterior median.

None
prune bool

Drop cells below δ / N_cells (False: the dropped mass is recorded but nothing is dropped).

False
delta float

Reporting precision (default DELTA).

DELTA
jitter_range (float, float)

With jitter=None, the σ_J prior bounds (mas, default JITTER_RANGE): widen the ceiling for large separations.

required
n_is int

Importance draws per cell.

N_IS
max_seconds float

Time cap on the whole run.

float('inf')
workers int

Cells run at once, in threads (default N_WORKERS, one: inline); the first cell runs alone, as it compiles the kernels and draws the sets. The result does not depend on it: each cell has its own key. Two threads cost about 0.3 GB more.

N_WORKERS
**leg_kwargs

Other arguments of position_leg.

{}

Returns:

Type Description
CellsResult

Raises:

Type Description
RuntimeError

If max_seconds ran out.