Binary recovery with grid search and HMC
Install: this tutorial needs the
plotsextra (ChainConsumer) and, for its "As a pipeline" section, thepipelineextra:pip install "virgil-astro[plots,pipeline]".
Looking for faint companions at high resolution is often the first thing you do with an interferometric dataset, and often why you took it.
This tutorial recovers a binary from synthetic observables: a coarse likelihood grid first, then Hamiltonian Monte Carlo (HMC), plain and Fisher-reparametrized.
First, the imports.
Imports and setup
import logging
import shutil
import warnings
import jax
import jax.numpy as jnp
import numpy as onp
import matplotlib.pyplot as plt
from jax.flatten_util import ravel_pytree
warnings.filterwarnings("ignore", message="IProgress not found.*")
logging.getLogger("matplotlib.font_manager").setLevel(logging.ERROR)
shutil.rmtree("binary_run", ignore_errors=True) # the pipeline section writes here
import numpyro
import numpyro.distributions as dist
from numpyro.infer import MCMC, NUTS
from numpyro.infer.initialization import init_to_value
from virgil.grid_fit import likelihood_grid
from virgil.inference import fisher_projection, hessian_matrix
from virgil.likelihood import loglike, posterior_predictive_summary
from virgil.models import BinaryModelCartesian
from virgil.oidata import OIData
from virgil.plotting import (
set_style,
plot_data_model_correlation,
plot_grid_map,
plot_chainconsumer_diagnostics,
diagnostics_table_from_samples,
truth_cartesian_and_polar,
)
set_style() # the figure style used throughout the docs
Simulate Data
We simulate \(V^2\) and phases from a known binary, add realistic noise, and wrap the result in the OIData object that virgil uses for data.
rng = onp.random.default_rng(42)
n_bl = 24
u = jnp.array(rng.uniform(-28.0, 28.0, size=n_bl))
v = jnp.array(rng.uniform(-28.0, 28.0, size=n_bl))
wavel = jnp.array([4.8e-6])
truth = {"dra": 120.0, "ddec": -80.0, "flux": 4e-3}
model_true = BinaryModelCartesian(**truth)
cvis_true = model_true.model(u, v, wavel)
vis_true = jnp.abs(cvis_true) ** 2
phi_true = jnp.rad2deg(jnp.angle(cvis_true))
# Synthetic noise as percentage of data scale (phase in degrees), boosted SNR by 5x.
vis_scale = jnp.maximum(jnp.median(vis_true), 1e-6)
phi_scale = jnp.maximum(jnp.median(jnp.abs(phi_true)), 5.0)
d_vis = 0.001 * vis_scale * jnp.ones_like(vis_true)
d_phi = 0.004 * phi_scale * jnp.ones_like(phi_true)
vis_obs = vis_true + d_vis * jnp.array(rng.normal(size=vis_true.shape))
phi_obs = phi_true + d_phi * jnp.array(rng.normal(size=phi_true.shape))
data = OIData(
{
"u": u,
"v": v,
"wavel": wavel,
"vis": vis_obs,
"d_vis": d_vis,
"phi": phi_obs,
"d_phi": d_phi,
"phi_unit": "deg",
"i_cps1": None,
"i_cps2": None,
"i_cps3": None,
"v2_flag": True,
"cp_flag": False,
}
)
Grid Search for Companions
JAX makes grid searches fast and easy to parallelize, so start any companion search here.
Define the grid dictionary samples in your chosen coordinates. We use Cartesian \((\Delta\mathrm{RA}, \Delta\mathrm{Dec}, \mathrm{flux})\); for separation, position angle and flux, use BinaryModelAngular instead.
samples = {
"dra": jnp.linspace(-250.0, 250.0, 81),
"ddec": jnp.linspace(-250.0, 250.0, 81),
"flux": 10 ** jnp.linspace(-4.5, -1.5, 60),
}
ll_cube = likelihood_grid(BinaryModelCartesian, data=data, grid=samples)
max_idx = jnp.unravel_index(jnp.argmax(ll_cube), ll_cube.shape)
grid_est = {
"dra": float(samples["dra"][max_idx[0]]),
"ddec": float(samples["ddec"][max_idx[1]]),
"flux": float(samples["flux"][max_idx[2]]),
}
print(
"Grid estimate: dra={:.3g} mas, ddec={:.3g} mas, flux={:.2g}".format(
grid_est["dra"], grid_est["ddec"], grid_est["flux"]
)
)
Grid estimate: dra=119 mas, ddec=-81.2 mas, flux=0.0038
Visualize the Grid
The plotting helpers give a consistent style and handle the metadata. The grid search alone recovers the binary accurately.
How significant is the best grid point? That needs the distribution of the search's best statistic under noise alone, which Detection ROC curves simulates.
# The full grid is reduced to the maximum log likelihood over flux at each
# (dra, ddec).
plot_grid_map(
ll_cube,
samples,
truth=truth,
best=grid_est,
label="Max log-likelihood over flux",
);

Uncertainty quantification with Hamiltonian Monte Carlo
Samplers such as Metropolis-Hastings or emcee often struggle in high dimensions. With JAX gradients we can use Hamiltonian Monte Carlo, which scales to many parameters, through numpyro:
params = ["dra", "ddec", "flux"]
# Define a simple physical-parameter HMC model with bounded priors.
def model_hmc(oidata):
dra = numpyro.sample("dra", dist.Uniform(-300.0, 300.0))
ddec = numpyro.sample("ddec", dist.Uniform(-300.0, 300.0))
log10_flux = numpyro.sample("log10_flux", dist.Uniform(-6.0, -1.0))
flux = 10.0**log10_flux
ll = loglike([dra, ddec, flux], params, BinaryModelCartesian, oidata)
numpyro.factor("loglike", ll)
# Initialize near the grid maximum for robust convergence in this toy setup.
init_values = {
"dra": float(grid_est["dra"]),
"ddec": float(grid_est["ddec"]),
"log10_flux": float(jnp.log10(max(grid_est["flux"], 1e-12))),
}
kernel = NUTS(model_hmc, init_strategy=init_to_value(values=init_values))
mcmc = MCMC(
kernel, num_warmup=800, num_samples=2000, num_chains=1, progress_bar=False
)
mcmc.run(jax.random.PRNGKey(2026), oidata=data)
posterior = mcmc.get_samples()
summary = {
"dra_median": float(jnp.median(posterior["dra"])),
"ddec_median": float(jnp.median(posterior["ddec"])),
"flux_median": float(jnp.median(10.0 ** posterior["log10_flux"])),
}
print(
"HMC estimate: dra={:.3g} mas, ddec={:.3g} mas, flux={:.2g}".format(
summary["dra_median"], summary["ddec_median"], summary["flux_median"]
)
)
HMC estimate: dra=120 mas, ddec=-80.1 mas, flux=0.0039
Diagnostic Tables
Helper functions turn the posterior draws into a dataframe.
# Convert vanilla posterior samples into diagnostics table for later comparison plots.
hmc_results = diagnostics_table_from_samples(
posterior,
flux_key="log10_flux",
log10_flux=True,
)
print(
"HMC estimate from diagnostics table: dra={:.3g} mas, ddec={:.3g} mas, flux={:.2g}".format(
float(hmc_results["dra"].median()),
float(hmc_results["ddec"].median()),
float(hmc_results["flux"].median()),
)
)
HMC estimate from diagnostics table: dra=120 mas, ddec=-80.1 mas, flux=0.0039
Fisher Reparametrization
If HMC converges slowly on high-SNR data, the cause is often strong correlations between parameters. zodiax, the backend of virgil, can reparametrize a problem into its natural scales, from fiducial values x0 and the Fisher Information Matrix.
See this zodiax tutorial for more.
x0_dict = {
"dra": grid_est["dra"],
"ddec": grid_est["ddec"],
"log10_flux": float(jnp.log10(max(grid_est["flux"], 1e-12))),
}
x0, unravel = ravel_pytree(x0_dict)
# Build local Fisher geometry around x0 for whitening transform.
def objective(x):
xdict = unravel(x)
flux = 10.0 ** xdict["log10_flux"]
values = jnp.array([xdict["dra"], xdict["ddec"], flux])
return -loglike(values, params, BinaryModelCartesian, data)
F = hessian_matrix(objective, x0)
P = fisher_projection(F)
# Sample in latent coordinates and apply explicit prior correction back to physical priors.
def model_hmc_fisher(oidata):
u_latent = numpyro.sample(
"u", dist.Normal(0.0, 1.0).expand([x0.shape[0]]).to_event(1)
)
log_q_u = dist.Normal(0.0, 1.0).log_prob(u_latent).sum()
x = x0 + jnp.dot(
P, u_latent
) # this maps it to the original physical space
xdict = unravel(x)
dra = xdict["dra"]
ddec = xdict["ddec"]
log10_flux = xdict["log10_flux"]
flux = 10.0**log10_flux
numpyro.deterministic("dra", dra)
numpyro.deterministic("ddec", ddec)
numpyro.deterministic("flux", flux)
log_prior_x = (
dist.Uniform(-300.0, 300.0).log_prob(dra)
+ dist.Uniform(-300.0, 300.0).log_prob(ddec)
+ dist.Uniform(-6.0, -1.0).log_prob(log10_flux)
)
numpyro.factor("prior_correction", log_prior_x - log_q_u)
numpyro.factor(
"loglike",
loglike([dra, ddec, flux], params, BinaryModelCartesian, oidata),
)
kernel_f = NUTS(model_hmc_fisher)
mcmc_f = MCMC(
kernel_f,
num_warmup=800,
num_samples=2000,
num_chains=1,
progress_bar=False,
)
mcmc_f.run(jax.random.PRNGKey(2027), oidata=data)
post_f = mcmc_f.get_samples()
print(
"Fisher HMC estimate: dra={:.3g} mas, ddec={:.3g} mas, flux={:.2g}".format(
float(jnp.median(post_f["dra"])),
float(jnp.median(post_f["ddec"])),
float(jnp.median(post_f["flux"])),
)
)
Fisher HMC estimate: dra=120 mas, ddec=-80.1 mas, flux=0.0039
Converting coordinate systems
The sample reformatter also converts coordinates:
# Convert Fisher-HMC posterior samples and prepare shared diagnostic tables.
fisher_results = diagnostics_table_from_samples(post_f)
truth_cart, truth_polar = truth_cartesian_and_polar(truth)
print(
"Fisher HMC estimate: sep={:.3g} mas, pa={:.3g} deg".format(
float(fisher_results["sep"].median()),
float(fisher_results["pa"].median()),
)
)
Fisher HMC estimate: sep=144 mas, pa=124 deg
Corner plots can come from anything you like, e.g. corner.py or pairplots; virgil has default helpers for chainconsumer.
The Fisher and default parametrizations work equally well, recovering the true values to about 1σ. The first plot is a corner plot. The second is a trace: check that the chains look stationary. chainconsumer and similar packages also give convergence diagnostics.
# Cartesian comparison plot
plot_chainconsumer_diagnostics(
{
"HMC Cartesian": hmc_results,
"Fisher-HMC Cartesian": fisher_results,
},
columns=["dra", "ddec", "flux"],
truth=truth_cart,
colors=["#1f77b4", "#ff7f0e"],
);


And in polar coordinates:
# Polar comparison plot
plot_chainconsumer_diagnostics(
{
"HMC Polar": hmc_results,
"Fisher-HMC Polar": fisher_results,
},
columns=["sep", "pa", "flux"],
truth=truth_polar,
colors=["#1f77b4", "#ff7f0e"],
);


Posterior Predictive Checks with Correlation Plots
Always compare the posterior predictions with the data. Interferometric data are hard to visualize, so the usual check is a 1:1 correlation plot of data against model.
# Posterior predictive correlation: data vs model (HMC and Fisher-HMC)
hmc_samples = {
"dra": posterior["dra"],
"ddec": posterior["ddec"],
"flux": 10.0 ** posterior["log10_flux"],
}
hmc_pred = posterior_predictive_summary(hmc_samples, BinaryModelCartesian, data)
fisher_samples = {key: post_f[key] for key in ("dra", "ddec", "flux")}
fisher_pred = posterior_predictive_summary(
fisher_samples, BinaryModelCartesian, data
)
plot_data_model_correlation(
data,
{"HMC": hmc_pred, "Fisher-HMC": fisher_pred},
colors=["C0", "C1"],
)
plt.show()

As a pipeline
BinaryPipeline runs everything above in one call, fixes the order of the steps and writes a run folder that reloads without recomputing. The grid search and maps are its search stage, the maximum-likelihood point starts its fit stage, and the HMC chains are its posterior stage. The cell below sets only this notebook's choices: the same \(\pm 250\) mas grid of 81 points per axis, a flux axis of 1000 points over \(10^{-5}\) to \(10^{-1}\) (a finer, wider axis than the hand-written grid: the pipeline warns when the axis does not resolve the flux peak, or when contrast limits fall outside it) and the same sampler length. Its priors are the pipeline's group-invariant defaults (uniform in position, log-uniform in flux), so the posterior matches the hand-written one to within sampling noise, not exactly.
The printed \(\chi^2/N\) is well below one at the fit, and the chi2 check says the errors are likely overestimated. In this simulation they are not: the data were drawn with exactly the quoted errors. For 48 data the lower tail is \(P(\chi^2_{48}/48 \le 0.48) \approx 9 \times 10^{-4}\), so the value printed at the true parameters is an unlucky draw of roughly one in a thousand for this seed. The warning is a false alarm here. On real data such a low value would deserve suspicion, and the likely cause would be errors that are too large. The convergence and stage_warnings warnings count the few grid positions where the flux refinement did not converge; res.describe() lists them.
from virgil.imaging import chi2_by_observable
from virgil.pipeline import BinaryPipeline
res = BinaryPipeline(
data,
BinaryModelCartesian(dra=100.0, ddec=-100.0, flux=1e-3),
output="binary_run",
max_sep_mas=250.0,
grid_step_mas=6.25, # 81 points from -250 to 250 mas
flux_range=[1e-5, 1e-1],
n_flux=1000, # fine enough to resolve the flux peak across 4 decades
num_warmup=800,
num_samples=2000,
num_chains=1,
).run()
s = res.summary
print(f"best grid point: dra={s['search']['dra_mas']:.1f} mas, ddec={s['search']['ddec_mas']:.1f} mas, "
f"{s['search']['local_nsigma']:.1f} sigma (local)")
print(f"companion: sep={s['companion']['sep_mas']:.1f} mas, pa={s['companion']['pa_deg']:.1f} deg, "
f"flux={s['companion']['flux']:.4f}")
print(f"chi2/N, quoted errors: {s['fit']['chi2_reduced']:.2f} at the fit, "
f"{chi2_by_observable(model_true, data)['chi2_red']['total']:.2f} at the truth (N = {data.vis.size + data.phi.size})")
print(f"r_hat {s['posterior']['r_hat_max']:.2f}, bulk ESS {s['posterior']['ess_bulk_min']:.0f}")
print({c.name: c.status for c in res.checks if c.status != "pass"})
best grid point: dra=118.8 mas, ddec=-81.2 mas, 12.9 sigma (local)
companion: sep=144.1 mas, pa=123.8 deg, flux=0.0039
chi2/N, quoted errors: 0.40 at the fit, 0.48 at the truth (N = 48)
r_hat 1.00, bulk ESS 1132
{'chi2': 'warn', 'convergence': 'warn', 'stage_warnings': 'warn'}