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

Source: Desdoigts et al. (2025), arXiv:2510.09806, simplified: visibilities on the half-plane of a square uv grid; a cell of mask transfer m has log-amplitude and phase error sigma / m. SVD modes (flux and position projected out) are kept to a fraction keep of the precision. 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 (about 0.2 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 (real 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.

One squared visibility at the centre of each splodge, that is at each baseline between two holes (as in AMICAL), and the closure phases of every triangle: 21 V² and 35 closure phases for the 7-hole NIRISS mask.

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`	Zero-valued data, for `with_model`. Each baseline carries its hole pair (numbered from 1, in the order of `holes`) as station indices, so the data can be written to OIFITS.

`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 telescope pair at each hour angle and channel, with the closure phases of every triangle; the defaults resemble VLTI/MATISSE in the L band with the four UTs. Bandwidth smearing (MATISSE LOW, R ~ 30) is modelled only if you opt in with OIData.with_bandwidth.

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 night, given as the MJD of the target's transit: each is a frame at `night + hour_angle / 24` (for scenes that change with time). By default the data have no times.	`None`

Returns:

Type	Description
`OIData`	Zero-valued data, 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`