`virgil.coverage`

Synthetic uv coverage and noise for simulations, computed on the fly: AMI as AMIGO represents it (a uv grid with a splodge-weighted mode basis) and as a classical masking observation (V² and closure phases at the splodge centres), and a long-baseline observation with Earth-rotation tracks and spectral channels (VLTI/MATISSE-like).

Synthetic uv coverage and noise, for simulating data from a known truth.

Each function returns data whose values are zero, to be filled from a model with OIData.with_model. They are computed on the fly, so tests and tutorials need no large data files.

:func:ami_grid_record: AMI as AMIGO represents it, with complex visibilities on a fine uv grid and a projection onto an orthonormal basis of modes weighted by the mask's splodges (an AMIGO mixed-DISCO record).
:func:nrm_oidata: the same mask as a classical non-redundant masking observation, with squared visibilities at the splodge centres and closure phases (as in AMICAL).
:func:vlti_oidata: a long-baseline observation, V² and closure phases along Earth-rotation tracks in several spectral channels (VLTI/MATISSE with the four UTs by default).

`ami_grid_record(wavelength_m=4.3e-06, pitch_m=0.3, rotation_deg=0.0, sigma=0.0001, keep=0.99, holes=NIRISS_AMI_HOLES, diameter=NIRISS_AMI_HOLE_DIAMETER)`

A simulated AMI record in AMIGO's form: a uv grid and a mode basis.

This follows the construction of AMIGO's latent visibility basis (Desdoigts et al. 2025, arXiv:2510.09806) in simplified form. The complex visibilities live on the half-plane of a square uv grid (as on the detector's Fourier grid, rotated on the sky by rotation_deg, the parallactic angle). Their information is weighted by the mask's transfer function: a cell where the splodges have transfer m measures the log-amplitude and phase of the visibility with error sigma / m. The responses to the source's flux (a constant log-amplitude) and position (phases linear in u and v) are projected out, and an SVD of what remains gives orthonormal modes, kept in order of precision until a fraction keep of the total precision is retained. The modes are the DISCO coefficients of the record, with independent errors.

The coefficients are zero: fill them with OIData.with_model.

Parameters:

Name	Type	Description	Default
`wavelength_m`	`float`	Wavelength in metres (default 4.3 µm, like F430M).	`4.3e-06`
`pitch_m`	`float`	Grid spacing in metres. AMIGO products are sampled more finely (ν Hor: 0.2165 m); a coarser grid keeps simulations small.	`0.3`
`rotation_deg`	`float`	Position angle, North to East, of the grid's "up" axis.	`0.0`
`sigma`	`float`	Error of a cell's log-amplitude and phase where the transfer is one (ν Hor's DISCO errors are ~5e-5 to 3e-4).	`0.0001`
`keep`	`float`	Fraction of the precision kept (AMIGO uses 0.99).	`0.99`
`holes`	`optional`	The mask (default: NIRISS AMI).	`NIRISS_AMI_HOLES`
`diameter`	`optional`	The mask (default: NIRISS AMI).	`NIRISS_AMI_HOLES`

Returns:

Type	Description
`dict`	A record for `OIData`.

`nrm_oidata(wavelength_m=4.3e-06, rotation_deg=0.0, sigma_v2=0.01, sigma_cp_deg=0.5, holes=NIRISS_AMI_HOLES)`

A simulated non-redundant masking observation: V² and closure phases.

The classical reduction of aperture masking (as in AMICAL), with one squared visibility at the centre of each splodge, that is at each baseline between two holes, and the closure phases of every triangle of holes. For the 7-hole NIRISS mask that is 21 V² and 35 closure phases.

Parameters:

Name	Type	Description	Default
`wavelength_m`	`float`	Wavelength in metres.	`4.3e-06`
`rotation_deg`	`float`	Position angle, North to East, of the mask's "up" axis on the sky.	`0.0`
`sigma_v2`	`float`	Error of each squared visibility.	`0.01`
`sigma_cp_deg`	`float`	Error of each closure phase, in degrees (AMI on sky: ~0.1–1°).	`0.5`
`holes`	`array - like`	Hole centres in metres (default: NIRISS AMI).	`NIRISS_AMI_HOLES`

Returns:

Type	Description
`OIData`	Data with zero values, for `with_model`.

`vlti_oidata(stations=VLTI_UTS, declination_deg=-50.0, hour_angles_h=(-3.0, -1.5, 0.0, 1.5, 3.0), wavelengths_m=onp.linspace(3e-06, 4e-06, 11), sigma_v2=0.03, sigma_cp_deg=1.0, latitude_deg=PARANAL_LATITUDE_DEG, nights_mjd=None)`

A simulated long-baseline observation: V² and closure phases.

Every pair of telescopes is observed at each hour angle, as the Earth's rotation carries the baselines along tracks in the uv plane, in every wavelength channel; closure phases come from every triangle at each hour angle. The defaults resemble VLTI/MATISSE in the L band at low spectral resolution with the four UTs. MATISSE's LOW mode (R ~ 30) smears structure further than about R λ / B from the field centre (~170 mas here), which virgil does not model.

Parameters:

Name	Type	Description	Default
`stations`	`(array - like, shape(n_telescopes, 2))`	Telescope positions (East, North) in metres (default: the UTs).	`VLTI_UTS`
`declination_deg`	`float`	The target's declination.	`-50.0`
`hour_angles_h`	`sequence of float`	Hour angles of the snapshots, in hours.	`(-3.0, -1.5, 0.0, 1.5, 3.0)`
`wavelengths_m`	`array - like`	The spectral channels, in metres.	`linspace(3e-06, 4e-06, 11)`
`sigma_v2`	`float`	Error of each squared visibility.	`0.03`
`sigma_cp_deg`	`float`	Error of each closure phase, in degrees.	`1.0`
`latitude_deg`	`float`	The array's latitude (default: Paranal).	`PARANAL_LATITUDE_DEG`
`nights_mjd`	`sequence of float`	Repeat the snapshots on each of these nights, given as the MJD of the target's transit; each snapshot is then a frame at `night + hour_angle / 24` (for orbits and other scenes that change with time). By default the data have no times.	`None`

Returns:

Type	Description
`OIData`	Data with zero values, for `with_model`. Each snapshot is a frame, and each baseline carries its station pair (numbered from 1), so `with_gains` applies.

`mask_transfer(u, v, holes=NIRISS_AMI_HOLES, diameter=NIRISS_AMI_HOLE_DIAMETER)`

The modulus of an aperture mask's optical transfer function.

The autocorrelation of the pupil, for circular holes of the given diameter, normalized to one at zero baseline: each hole pair gives a "splodge" around its baseline and the opposite one, and all holes together the central splodge.

Parameters:

Name	Type	Description	Default
`u`	`array - like`	Baselines in metres, in the frame of the mask.	required
`v`	`array - like`	Baselines in metres, in the frame of the mask.	required
`holes`	`(array - like, shape(n_holes, 2))`	Hole centres in metres (default: the NIRISS AMI mask).	`NIRISS_AMI_HOLES`
`diameter`	`float`	Hole diameter in metres (NIRISS: hexagons about 0.82 m across).	`NIRISS_AMI_HOLE_DIAMETER`