virgil

Versatile Interferometric Reconstruction and Gradient-based Inference Library.

Contributors: Dori Blakely, Benjamin Pope, Louis Desdoigts, Shashank Dholakia, Toon De Prins, Jonah Goldfine, Max Charles.

facilis descensus averno

What is virgil?

virgil is a package for modelling optical interferometry data in JAX. It is a one-stop shop for fitting parametric models and for image reconstruction, accelerated on GPU and HPC.

Installation

virgil is hosted on PyPI; the easiest way to install it is:

pip install virgil-astro

Optional extras add the corner-plot helpers in virgil.plotting (pip install "virgil-astro[plots]", for pandas and ChainConsumer) and the SIMBAD lookups in virgil.legacy ([legacy], for astroquery). Solving Kepler's equation in virgil.orbits needs jaxoplanet, which comes with pip install "virgil-astro[orbits]". virgil.orbits imports without it and loads jaxoplanet only when a Kepler-solving path is called (evaluating an orbit's positions or to_jaxoplanet); that call raises an error naming the extra if jaxoplanet is missing.

You can also build from source. To do so, clone the git repo and enter the directory:

git clone --filter=blob:none https://github.com/benjaminpope/virgil
cd virgil
pip install .

--filter=blob:none makes a partial clone: you get the full history, but old versions of files are fetched only if you ask for them. It skips large data files that are no longer used, so the download is about 15 MB rather than about 280 MB.

We recommend using a virtual environment to avoid dependency conflicts.

Using uv (recommended):

uv python install 3.11
uv venv --python 3.11 .venv
uv pip install --python .venv/bin/python -e ".[test]"
uv run --python .venv/bin/python pytest -q

Use & Documentation

Documentation is published at benjaminpope.github.io/virgil.

Using these docs

The sections in the sidebar hold worked examples on simulated and bundled data:

• Background: who contributed what, Gaussian-process priors and information field theory, and coordinate, sign and flux conventions.
• Data Handling: reading OIFITS files into OIData, and AMIGO's DISCO data from JWST aperture masking, and spectro-interferometric observables (OI_FLUX spectra, differential phases and calibration nuisances).
• Binaries: searching for companions, detection limits, detection ROC curves calibrated by injection and recovery, fitting several datasets together, and orbits from interferometric epochs (needs the [orbits] extra).
• Sources: visibility models, extended sources, composing scenes, spotted stars, limb-darkened stars and gravity-darkened stars.
• Imaging: image reconstruction in six parts: simulating data, regularised maximum likelihood, Gaussian-process priors, a ring around a binary, sampling the posterior and sparse images and CLEAN.
• API Reference documents every public class and function.

Documentation tooling is currently migrating from MkDocs to Zensical. During this transition, both builders are supported from the same configuration file.

Local docs checks:

uv run --python .venv/bin/python mkdocs build --strict
uv run --python .venv/bin/python zensical build --clean

Independent validation

virgil's own tests mostly check virgil against itself. The companion repository virgil-validation checks it against code that shares nothing with it: geometric primitives with textbook visibilities, uv tracks and OIFITS files built from first principles, and aperture-masking images simulated with dLux, which virgil then reads and fits. If you would like something else validated, please open an Issue there describing the model or function, the independent result it should match, and the precision you expect.

Collaboration & Development

We welcome collaboration and development contributions. See CONTRIBUTING.md for development setup, testing, and pull request workflow. Release notes are in the changelog.

Name

Why is it called virgil?

VIRGIL is the Versatile Interferometric Reconstruction and Gradient-based Inference Library. In Dante's Divine Comedy, the poet Virgil is Dante's guide through the Inferno and Purgatory. In Virgil's own Aeneid, when Aeneas enters the underworld he draws his sword on the monsters crowding its threshold. His guide, the Cumaean Sibyl, warns him that they are only thin, bodiless lives flitting in a hollow semblance of form (Aeneid VI.292–294). Image reconstruction from sparse interferometric data is full of false visions like these: artefacts that look like structure but have no substance in the data. VIRGIL aims to help you tell the difference. The acronym is Jonah Goldfine's.

Formerly drpangloss

Until version 0.1.1 this package was called drpangloss, after Voltaire's Dr Pangloss and as a nod to Antoine Mérand's CANDID. From version 0.2.0 it is virgil: import virgil, installed with pip install virgil-astro. A final release of drpangloss (0.2.0) under its own name depends on virgil-astro and points here, so old installs find the new package.

e quindi uscimmo a riveder le stelle