Skip to content

virgil.grid_fit

Grid searches. Contrast limits built on them are in virgil.limits.

Grid searches over model parameters.

Grids use indexing="ij": one output axis per grid key, in the order of grid (for dra, ddec, axis 0 is East, axis 1 North, so transpose a 2D map to show it North up; plot_grid_map does). The flux optimized at each position is the one key ending in flux, unless flux_param says otherwise; fluxes are companion/primary (see virgil.limits for contrast and Δmag, and for contrast limits). See Grid searches.

LinearFluxGrid

Bases: NamedTuple

Result of linear_flux_grid.

The last three fields are None unless a prior was given.

flux instance-attribute

flux_error instance-attribute

snr instance-attribute

posterior_mean = None class-attribute instance-attribute

posterior_sd = None class-attribute instance-attribute

log_bayes_factor = None class-attribute instance-attribute

LogUniform

Bases: NamedTuple

Log-uniform (scale-invariant) prior on the companion flux ratio.

p(f) = 1 / (f ln(f_max / f_min)) on f_min <= f <= f_max, with 0 < f_min < f_max finite, in units of the companion/primary flux. See Grid searches.

f_min instance-attribute

f_max instance-attribute

Gaussian

Bases: NamedTuple

Gaussian prior N(mean, sd**2) on the companion flux ratio.

Its support includes negative flux: a closed form only. Prefer LogUniform.

mean instance-attribute

sd instance-attribute

likelihood_grid(model, *, data, grid, batch_size=None)

Evaluate the log likelihood at every point of a parameter grid.

Only model may be positional: likelihood_grid(model, data=data, grid=grid) (the 0.3 order warns until 0.5).

Parameters:

Name Type Description Default
model SourceModel or class

Template model whose parameters at the paths in grid are varied (e.g. a System with "comp.dra"), or a model class called with grid's keys as keywords.

 required
data OIData

Data to fit.

 required
grid dict[str, array - like]

Parameter name or path to 1D values (dra/ddec in mas, flux as companion/primary); the output has one axis per key, in this order.

 required
batch_size int

Grid points evaluated at once (default about 220 model visibilities on a CPU, 223 elsewhere, at least 256); smaller bounds memory.

 None

Returns:

Type Description
array - like

Log likelihood of shape tuple(len(v) for v in grid.values()).

optimized_likelihood_grid(model, data, grid, *, flux_param=None, batch_size=None)

optimized_flux_grid(model, data, grid, *, flux_param=None, batch_size=None)

linear_flux_grid(model, data, grid, *, flux_param=None, batch_size=None, n_iter=0, prior=None)

Linearized best-fit companion flux at every grid position, in closed form.

A fast first pass beside optimized_flux_grid: for a faint companion the residuals are linear in the flux, so one model evaluation per position gives the flux (either sign) and its error. Raise n_iter for a bright companion; see Grid searches.

Source: Luger et al. (2017), references; compare with fouriever's lincmap (closure or kernel phases only).

Parameters:

Name Type Description Default
model

As for optimized_flux_grid. At zero flux model must reduce to the primary alone. The flux axis of grid is ignored (the flux is solved for) but must name the parameter.

 required
data

As for optimized_flux_grid. At zero flux model must reduce to the primary alone. The flux axis of grid is ignored (the flux is solved for) but must name the parameter.

 required
grid

As for optimized_flux_grid. At zero flux model must reduce to the primary alone. The flux axis of grid is ignored (the flux is solved for) but must name the parameter.

 required
flux_param

As for optimized_flux_grid. At zero flux model must reduce to the primary alone. The flux axis of grid is ignored (the flux is solved for) but must name the parameter.

 required
batch_size

As for optimized_flux_grid. At zero flux model must reduce to the primary alone. The flux axis of grid is ignored (the flux is solved for) but must name the parameter.

 required
n_iter int

Gauss-Newton relinearization steps after the first at f = 0.

 0
prior numpyro LogUniform or Normal

Prior on f, filling the posterior and Bayes-factor fields. It must be a scalar distribution with both bounds (LogUniform) or both parameters (Normal), and the Bayes factor depends on the bounds, so choose them (see Grid searches).

 None

Returns:

Type Description
LinearFluxGrid

Named tuple of arrays with one axis per coordinate key: flux, flux_error (NaN where the model ignores the flux), snr (flux over error), and with a prior posterior_mean, posterior_sd and log_bayes_factor (per position; > 0 favours a companion; else None).

Examples:

>>> axis = np.linspace(-300.0, 300.0, 61)
>>> grid = {"dra": axis, "ddec": axis, "flux": np.array([1e-3])}
>>> res = linear_flux_grid(BinaryModelCartesian, data, grid)

laplace_flux_uncertainty_grid(model, data, grid, flux=None, *, flux_param=None, batch_size=None)

Laplace uncertainty of the flux at every grid position.

The inverse square root of the curvature of the negative log likelihood along the flux, with the coordinates held fixed.

Parameters:

Name Type Description Default
model

As for optimized_flux_grid.

 required
data

As for optimized_flux_grid.

 required
grid

As for optimized_flux_grid.

 required
flux_param

As for optimized_flux_grid.

 required
batch_size

As for optimized_flux_grid.

 required
flux array - like

Flux at which to evaluate the curvature, one axis per coordinate key (default: the optimized_flux_grid best fit, the mean ruffio_upperlimit expects).

 None

Returns:

Type Description
array - like

One-sigma flux uncertainty per coordinate-key point; NaN where the curvature is not positive.

best_grid_point(loglike_grid, grid)

Return the grid point with the highest log likelihood.

Parameters:

Name Type Description Default
loglike_grid array - like

Output of likelihood_grid for grid, with one axis per key. NaNs are ignored.

 required
grid dict[str, array - like]

The grid axes used to compute loglike_grid.

 required

Returns:

Type Description
dict[str, float]

{name: value} at the maximum, in the order of grid.