Metadata-Version: 2.4
Name: virgil-astro
Version: 0.4.0
Summary: VIRGIL, the Versatile Interferometric Reconstruction and Gradient-based Inference Library: modelling and imaging interferometric data in JAX.
Author: Max Charles, Jonah Goldfine
Author-email: Benjamin Pope <benjamin.pope@mq.edu.au>, Dori Blakely <blakelyd@uvic.ca>, Shashank Dholakia <shashankdholakia1@gmail.com>, Toon De Prins <toon.deprins@protonmail.com>, Louis Desdoigts <ldes9555@uni.sydney.edu.au>
License-Expression: MIT
Project-URL: Homepage, https://github.com/benjaminpope/virgil
Project-URL: Documentation, https://benjaminpope.github.io/virgil/
Project-URL: Changelog, https://github.com/benjaminpope/virgil/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/benjaminpope/virgil/issues
Project-URL: Repository, https://github.com/benjaminpope/virgil
Keywords: interferometry,oifits,aperture-masking,astronomy,jax,autodiff,differentiable,image-reconstruction,virgil
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jax>=0.8.0
Requires-Dist: jaxbessel>=0.2.0
Requires-Dist: equinox>=0.13.2
Requires-Dist: zodiax>=0.4.1
Requires-Dist: optimistix>=0.1.0
Requires-Dist: lineax>=0.1.0
Requires-Dist: optax>=0.2.6
Requires-Dist: numpyro>=0.19.0
Requires-Dist: numpy>=2.0
Requires-Dist: nufftax>=0.6
Requires-Dist: scipy>=1.13
Requires-Dist: matplotlib>=3.8
Requires-Dist: astropy>=6.1
Provides-Extra: plots
Requires-Dist: pandas>=2.2.2; extra == "plots"
Requires-Dist: chainconsumer>=1.1.3; extra == "plots"
Provides-Extra: legacy
Requires-Dist: astroquery>=0.4.7; extra == "legacy"
Provides-Extra: orbits
Requires-Dist: jaxoplanet>=0.1.0; extra == "orbits"
Provides-Extra: radio
Requires-Dist: casatools>=6.6; python_version < "3.14" and extra == "radio"
Provides-Extra: integrations
Requires-Dist: virgil-astro[orbits]; extra == "integrations"
Provides-Extra: pipeline
Requires-Dist: h5py>=3.11; extra == "pipeline"
Requires-Dist: nbformat>=5.9; extra == "pipeline"
Requires-Dist: nbclient>=0.9; extra == "pipeline"
Requires-Dist: ipykernel>=6.25; extra == "pipeline"
Requires-Dist: virgil-astro[plots]; extra == "pipeline"
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-xdist>=3.5; extra == "test"
Requires-Dist: pytest-timeout>=2.3; extra == "test"
Requires-Dist: pyoifits>=0.4.10; extra == "test"
Requires-Dist: virgil-astro[pipeline,plots]; extra == "test"
Provides-Extra: notebooks
Requires-Dist: tqdm>=4.66; extra == "notebooks"
Requires-Dist: ipywidgets>=8.0; extra == "notebooks"
Requires-Dist: virgil-astro[integrations,plots]; extra == "notebooks"
Provides-Extra: docs
Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
Requires-Dist: mkdocs-material<10,>=9.6; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.30; extra == "docs"
Requires-Dist: zensical<0.1,>=0.0.62; extra == "docs"
Provides-Extra: dev
Requires-Dist: virgil-astro[docs,orbits,test]; extra == "dev"
Requires-Dist: ruff==0.11.0; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# virgil
[![PyPI version](https://badge.fury.io/py/virgil-astro.svg)](https://badge.fury.io/py/virgil-astro)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![integration](https://github.com/benjaminpope/virgil/actions/workflows/tests.yml/badge.svg)](https://github.com/benjaminpope/virgil/actions/workflows/tests.yml)
[![Documentation](https://github.com/benjaminpope/virgil/actions/workflows/zensical-pages.yml/badge.svg)](https://benjaminpope.github.io/virgil/)
<!-- dev-carbon-badge -->
[![dev carbon | 76.5 kg CO2e](https://img.shields.io/badge/dev%20carbon-76.5%20kg%20CO%E2%82%82e-2e7d32)](https://benjaminpope.github.io/virgil/dev_carbon/)
<!-- /dev-carbon-badge -->

**V**ersatile **I**nterferometric **R**econstruction and **G**radient-based **I**nference **L**ibrary.

Contributors: [Dori Blakely](https://github.com/blakelyd), [Benjamin Pope](https://github.com/benjaminpope), [Louis Desdoigts](https://github.com/LouisDesdoigts), [Shashank Dholakia](https://github.com/shashankdholakia), [Toon De Prins](https://github.com/DePrinsT), [Jonah Goldfine](https://github.com/JonahDG), [Max Charles](https://github.com/maxecharles).

*facilis descensus averno*

## What is virgil?

virgil models optical interferometry data in JAX. It fits parametric models and reconstructs images in one framework, and runs on GPUs and clusters.

## Stability

Everything public is **stable** (a change needs a deprecation cycle) except a list of **provisional** features that are new in 0.4 and may change in any 0.4.x release without one: orbit fitting across epochs and aliases, the `MultipoleDisk` family, Gaussian-process ensembles, variational inference, the pipelines, CLEAN and the image-recovery metrics. See the [list of provisional features](https://benjaminpope.github.io/virgil/stability/).

## Installation

Install virgil from PyPI, where it is called `virgil-astro`:

```
pip install virgil-astro
```

`pip install virgil` installs an unrelated package. Use Python 3.12 or newer: JAX 0.11 needs it, and Python 3.11 gets the last JAX release that supports it.

Optional extras: `pip install "virgil-astro[plots]"` adds pandas and
ChainConsumer for the corner plots in `virgil.plotting`, and `[legacy]` adds
astroquery for the SIMBAD lookups in `virgil.legacy`. `virgil.orbits` solves
Kepler's equation with
[jaxoplanet](https://github.com/exoplanet-dev/jaxoplanet), from
`pip install "virgil-astro[orbits]"`. The module imports without it; only
evaluating an orbit's positions or calling `to_jaxoplanet` needs it, and then
the error names the extra.

The tutorials are in the [GitHub repository](https://github.com/benjaminpope/virgil/tree/main/notebooks), not in the wheel. `pip install "virgil-astro[notebooks,pipeline]"` installs everything they use.

To build from source, clone the repository:

```
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
file versions download only when you ask for them. That skips large data files
no longer in use, so the download is about 15 MB rather than about 280 MB.

Work in a virtual environment. With `uv` (recommended):

```bash
uv python install 3.12
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -e ".[test]"
.venv/bin/python -m pytest tests/test_models_core.py -q
```

## Where to start

Documentation is published at [benjaminpope.github.io/virgil](https://benjaminpope.github.io/virgil/). New here? The [quickstart](https://benjaminpope.github.io/virgil/quickstart/) loads an OIFITS file and fits a binary in about twenty lines.

| I want to | Go to |
| --- | --- |
| Read my OIFITS file | [Reading data](https://benjaminpope.github.io/virgil/data_io/) |
| Find and fit a companion | [Binary search](https://benjaminpope.github.io/virgil/binary_search/) |
| Set a contrast limit or a detection limit | [Contrast limits](https://benjaminpope.github.io/virgil/contrast_limits/) |
| Fit a binary's orbit | [Which orbit tool?](https://benjaminpope.github.io/virgil/which_orbit_tool/), then [Orbits from interferometric data](https://benjaminpope.github.io/virgil/orbit_fitting/) |
| Make an image | [Simulating AMI data](https://benjaminpope.github.io/virgil/imaging_ami/), then [Regularized maximum likelihood](https://benjaminpope.github.io/virgil/imaging_rml/) |
| Run a whole analysis in one command | [Pipelines](https://benjaminpope.github.io/virgil/pipeline/) |
| Check which features may change | [Stability](https://benjaminpope.github.io/virgil/stability/) |

## Independent validation

virgil's own tests mostly check virgil against itself. The companion repository [virgil-validation](https://github.com/benjaminpope/virgil-validation) checks it against code that shares nothing with it: textbook visibilities for geometric primitives, uv tracks and OIFITS files built from first principles, and aperture-masking images simulated with [dLux](https://github.com/LouisDesdoigts/dLux) for virgil to read and fit. To ask for another check, [open an Issue there](https://github.com/benjaminpope/virgil-validation/issues) naming the model or function, the independent result it should match, and the precision you expect.

## Collaboration & Development

Contributions are welcome. [CONTRIBUTING.md](https://github.com/benjaminpope/virgil/blob/main/CONTRIBUTING.md) covers setup, testing and the pull-request workflow. Release notes are in the [changelog](https://github.com/benjaminpope/virgil/blob/main/CHANGELOG.md).

## Name

VIRGIL is the **V**ersatile **I**nterferometric **R**econstruction and **G**radient-based **I**nference **L**ibrary. 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). Images reconstructed from sparse interferometric data are full of such false visions: artefacts that look like structure but have no substance in the data. VIRGIL helps 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](https://github.com/amerand/CANDID). From version 0.2.0 it is **virgil**: `import virgil`, installed with `pip install virgil-astro`. A final `drpangloss` release (0.2.0) depends on `virgil-astro` and points here, so old installs find the new package.

*e quindi uscimmo a riveder le stelle*
