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 |
binding |
{'2dt_min', p_floor, p_range}
|
The term that sets |
a_hi, span, sigma_min |
float
|
The inputs of |
n0_mass |
float
|
Prior mass of the long-period band |
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
|
|
modes |
list of Mode
|
|
draws |
array or None
|
Resample-move posterior draws (chart vectors); |
log_w, x_is |
array
|
The importance draws and their log weights (exact, not resampled). |
at_floor |
bool
|
|
undersampled |
bool
|
|
unreliable |
bool
|
The ESS is below |
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 |
shared |
list of Mode
|
Neighbour modes that straddle a shared edge, in this cell's chart: extra
components of the mixture (not in |
info |
dict
|
The search's counts ( |
log_l_sup |
float
|
The largest |
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
|
|
cells |
list of Cell
|
|
fits |
list of CellFit
|
|
p_pos |
ndarray
|
|
below_delta |
ndarray
|
Cells with |
pruned |
ndarray
|
Cells actually dropped (all false unless |
pruned_mass |
float
|
|
jitter |
float
|
The position jitter used (mas). |
failed |
ndarray
|
Cells with a non-finite target, or at the floor ( |
upper, matters |
ndarray
|
|
omitted_bound |
float
|
The summed |
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_RANGE
|
p_range
|
(float, float)
|
Override |
None
|
gap_days
|
float
|
Nights closer than this merge (default 0.5 d, as |
GAP_DAYS
|
p_floor
|
float
|
The only other lower bound (days). |
_P_FLOOR
|
Returns:
| Type | Description |
|---|---|
PeriodDomain
|
With the binding term of |
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 |
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
|
|
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.
- Every minimal set of
search_plan, at each of the 17 ζ starts, on aln Pgrid of the cell; at every grid minimum a damped Newton in(ln P, ζ)on the set's variable-projection residual. - Candidates whose set residual exceeds its derived
χ²cut are dropped, the rest deduplicated by labels and(ln P, ζ). - C-steps (at most
N_C): Newton on the labelled target in the full chart, relabel, until the labels repeat. - Add-one: each outlier night with a peak tried as an inlier (C-steps and Newton), kept while the label-summed objective rises.
- 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 |
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
|
0.0
|
jitter_ref
|
float
|
With |
None
|
jitter_range
|
(float, float)
|
With |
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 |
"float64"
|
plan
|
dict
|
The sets of |
None
|
nu_width
|
float
|
The widest cell in |
None
|
shared
|
sequence of Mode
|
Neighbour modes in this cell's chart, extra mixture components
( |
()
|
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
|
|
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 |
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
|
From |
required |
domain
|
PeriodDomain
|
|
required |
key
|
PRNGKey
|
|
required |
log_outlier
|
array - like
|
Each night's |
None
|
outlier
|
OutlierPrior
|
The prior predictive for |
None
|
jitter
|
float
|
A fixed position jitter (mas), 0 for none. Default |
None
|
prune
|
bool
|
Drop cells below |
False
|
delta
|
float
|
Reporting precision (default |
DELTA
|
jitter_range
|
(float, float)
|
With |
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
|
**leg_kwargs
|
Other arguments of |
{}
|
Returns:
| Type | Description |
|---|---|
CellsResult
|
|
Raises:
| Type | Description |
|---|---|
RuntimeError
|
If |