Skip to content

virgil.arcs

Short arcs of an orbit: each night's velocity from its two halves, the periods (cycle counts) that the nights' positions and velocities admit, and each alias band's seed orbits.

Short arcs: the motion within and between nights narrows the alias bands.

Provisional

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

Nights far apart leave one alias band per whole number of cycles between them (alias_bands). Nights close together, and the motion within a night, see short arcs of the orbit, whose speed and curvature bound the period. night_motion measures each night's velocity from its two halves. unwrap_cycles joins the nights, shortest gap first, and keeps at each step the periods whose Thiele–Innes fit to the positions and velocities joined so far is close to the best, so each longer gap admits only the cycle counts that the shorter arcs allow. arc_profile gives each band's best orbits, which seed fit_orbit_aliases. The orbit tutorial gives the reasoning.

NightMotion dataclass

Each night's angular velocity, from night_motion.

Attributes:

Name Type Description
mjd ndarray

Each night's time (MJD), as in the positions.
vel ndarray

(n, 2) velocity (mas/day, East and North); 0 where not measured.
cov ndarray

(n, 2, 2) covariance (mas²/day²); the identity where not measured.
measured ndarray

Whether each night's velocity was measured.

mjd instance-attribute

vel instance-attribute

cov instance-attribute

measured instance-attribute

__init__(mjd, vel, cov, measured)

take(keep)

The nights selected by keep (a mask or indices).

CycleCounts dataclass

The periods the short arcs admit, from unwrap_cycles.

Attributes:

Name Type Description
intervals tuple of (float, float)

The admissible periods (days), disjoint and increasing.
steps tuple of dict

One per constraining step: the nights joined (mjd), the baseline (days), dof, the best chi2, the error scale and the admissible intervals after it.

intervals instance-attribute

steps instance-attribute

__init__(intervals, steps)

admits(band)

Whether band (an AliasBand) overlaps an admissible interval.

night_motion(data, positions, *, max_shift=_MAX_SHIFT, jitter=ARC_JITTER, cov_scale=1.0)

Each night's angular velocity, from the positions of its two halves.

Each night's frames are split into an earlier and a later half, each refined from the night's (epoch_positions) position on the same scale-marginalized surface, with the same primary. The velocity is the difference over the time between them, with a covariance floor of jitter λ/B_max. A night with one frame, or whose halves move more than max_shift λ/B_max, has none.

Parameters:

Name Type Description Default
data Epochs or sequence of OIData

The nights, in the order of positions.

 required
positions EpochPositions

Each night's position.

 required
max_shift float

The furthest a half may move from the night's position, and each half's position floor, in λ/B_max (defaults 0.5, ARC_JITTER).

 _MAX_SHIFT
jitter float

The furthest a half may move from the night's position, and each half's position floor, in λ/B_max (defaults 0.5, ARC_JITTER).

 _MAX_SHIFT
cov_scale float

Factor (at least 1) multiplying the halves' covariances, σ by its square root, before the floor is added (default 1).

 1.0

Returns:

Type Description
NightMotion

unwrap_cycles(positions, motion=None, *, p_range, ecc_max=0.9, jitter_mas=0.0, cov_scale=1.0, delta_chi2=ARC_DELTA_CHI2, k=9.0, eccs=None)

The periods that the short arcs admit, unwrapping the cycle counts.

The nights are joined into arcs shortest gap first. Where an arc has more measured coordinates than the seven orbital parameters, each period is scored by its best Thiele–Innes fit and kept while its χ² is within delta_chi2 * max(1, chi2_min / dof) of the best. Too few data leave the whole window: weak constraints keep more periods, never fewer.

Parameters:

Name Type Description Default
positions PositionData

The nights' positions.

 required
motion NightMotion

The nights' velocities (night_motion).

 None
p_range (float, float)

The period window (days).

 required
ecc_max optional

The largest eccentricity; a position floor (mas); the factor (at least 1) multiplying the positions' covariances, σ by its square root (match cov_scale in night_motion); the χ² margin; the phase coherence of the period grids; trial eccentricities (default 0 to ecc_max in steps of 0.05).

 0.9
jitter_mas optional

The largest eccentricity; a position floor (mas); the factor (at least 1) multiplying the positions' covariances, σ by its square root (match cov_scale in night_motion); the χ² margin; the phase coherence of the period grids; trial eccentricities (default 0 to ecc_max in steps of 0.05).

 0.9
cov_scale optional

The largest eccentricity; a position floor (mas); the factor (at least 1) multiplying the positions' covariances, σ by its square root (match cov_scale in night_motion); the χ² margin; the phase coherence of the period grids; trial eccentricities (default 0 to ecc_max in steps of 0.05).

 0.9
delta_chi2 optional

The largest eccentricity; a position floor (mas); the factor (at least 1) multiplying the positions' covariances, σ by its square root (match cov_scale in night_motion); the χ² margin; the phase coherence of the period grids; trial eccentricities (default 0 to ecc_max in steps of 0.05).

 0.9
k optional

The largest eccentricity; a position floor (mas); the factor (at least 1) multiplying the positions' covariances, σ by its square root (match cov_scale in night_motion); the χ² margin; the phase coherence of the period grids; trial eccentricities (default 0 to ecc_max in steps of 0.05).

 0.9
eccs optional

The largest eccentricity; a position floor (mas); the factor (at least 1) multiplying the positions' covariances, σ by its square root (match cov_scale in night_motion); the χ² margin; the phase coherence of the period grids; trial eccentricities (default 0 to ecc_max in steps of 0.05).

 0.9

Returns:

Type Description
CycleCounts

arc_profile(positions, motion, bands, *, ecc_max=0.9, jitter_mas=0.0, cov_scale=1.0, k=9.0, n_best=3, eccs=None, sign_free=False)

Each band's best orbits from the positions and the velocities.

As position_profile, with each night's velocity in the Thiele–Innes fit as well, the positions' covariances times cov_scale and a position floor jitter_mas (mas) added in quadrature. With sign_free the sign-free orbits of the positions alone are added (n_best of each).

Returns:

Type Description
list of dict

Per band: n, chi2 (best), period of the best orbit and the orbits [(KeplerOrbit, χ²), ...].