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, Anand Sivaramakrishnan, Ian Czekala and Jens Kammerer. The Contributors page says who did what.

What is virgil?

virgil is a package for modelling optical interferometry data in JAX.

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).

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, and Gaussian-process priors and information field theory.
• Data Handling: reading OIFITS files into OIData, and AMIGO's DISCO data from JWST aperture masking.
• Binaries: searching for companions, detection limits, and fitting several datasets together.
• Sources: visibility models, extended sources, composing scenes, spotted stars and gravity-darkened stars.
• Imaging: image reconstruction in five parts: simulating data, regularised maximum likelihood, Gaussian-process priors, a ring around a binary and sampling the posterior.
• 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 under its own name will depend on virgil-astro and point here, so old installs find the new package.