Instrument and software conventions

hyperdrive was written for the MWA, and two of its conventions differ from those of casacore-based software (CASA, DP3 and LOFAR, WSClean, ASKAPsoft) and from OSKAR:

  • the polarisation convention: how Stokes I, Q, U, V map onto the instrumental XX, XY, YX, YY (see Polarisations);
  • the UVW frame: where the array is placed when the UVWs (and so the phases) are computed, and which way round a baseline is.

The types that name these live in Marlu (marlu::convention), so that hyperdrive, Birli and any other Marlu user agree on them and on how files record them.

Where the conventions come from

Every subcommand that models sky-model visibilities (vis-simulate, di-calibrate, vis-subtract, peel, vis-utils simulate) models in a polarisation convention and a UVW frame, chosen in this order:

  1. --pol-convention and --uvw-frame, if given;
  2. --convention, a preset for both;
  3. the conventions recorded in, or implied by, the input data (see below);
  4. the MWA's (vis-simulate has no input data, so this is its default).

The chosen conventions and where they came from are printed at startup. All three arguments can also be given in an arguments file (convention = "lofar", pol_convention = "iau", uvw_frame = "casacore" in the [model] section).

--conventionpolarisationsUVW framefor
mwamwahyperdriveMWA data and hyperdrive's own outputs
iau (alias casa)iauhyperdriveIAU polarisations without the casacore frame, e.g. Measurement Sets CASA itself writes (see the note on CASA below)
lofariaucasacoreLOFAR data, DP3
casacore (aliases wsclean, uvh5, pyuvdata)iaucasacoreMeasurement Sets whose UVWs casacore or DP3 computed; UVH5 files
askap (alias askapsoft)askapcasacoreASKAPsoft
oskarmwaoskarOSKAR simulations

--pol-convention accepts mwa (alias oskar), iau (aliases lofar, casacore, wsclean), askap (alias askapsoft), or the two parts spelled as UVH5 does: east or north for the X orientation, optionally followed by /avg or /sum for the Stokes convention (iau is north/avg, askap is north/sum).

--uvw-frame accepts hyperdrive (aliases marlu, mwa, aips, casa), casacore (aliases lofar, wsclean, askap, uvh5, pyuvdata), oskar and cotter.

UVW frames

Visibilities are always \( V = \sum_s S_s \exp(2 \pi i (u l + v m + w (n-1))) \); the frames differ in how \( (u, v, w) \) relate to the antenna positions.

In the hyperdrive frame (Marlu 0.20 and later) the array is precessed (and nutated) to J2000 and rotated with the apparent local sidereal time, the J2000 baselines are rotated by the rigid rotation that takes the annual aberration of the phase centre out (as casacore's MeasMath::deapplyAberration does), and a baseline is antenna 1 minus antenna 2, as Birli writes and as the uvfits (AIPS) convention has it.

The casacore frame reproduces the J2000 UVWs that casacore's calculators compute (MBaseline ITRF → J2000; derivedmscal's UVWJ2000, measures.to_uvw), which DP3 uses. It is the hyperdrive frame with the opposite baseline sign (antenna 2 minus antenna 1), so the modelled visibilities are the complex conjugates of the hyperdrive frame's. Marlu's implementation matches python-casacore to better than 1 cm on 2 km baselines. The frame needs precession (--no-precession disables it with a warning).

The cotter frame is cotter's, and the hyperdrive frame of Marlu before 0.20 (so of hyperdrive and Birli releases built on it): the array is rotated with the mean sidereal time and the precessed positions are projected onto the aberrated phase centre. The two differences are each about 20 arcsec; w differs from the hyperdrive frame's by up to about 8 cm per km of baseline, and u and v are rolled by a few arcsec about the phase centre. Use it to model data whose UVWs cotter, Birli --emulate-cotter or an older hyperdrive or Birli computed, so the model matches their UVWs. It needs precession too.

Note that not everything casacore-based uses the casacore frame's baseline sign. The Measurement Sets CASA itself writes (importevla, importuvfits) have antenna 1 minus antenna 2 baselines, as do cotter's and Birli's, and pyuvdata assumes that of any Measurement Set or uvfits file it did not write. pyuvdata's own uvw_array (and so UVH5) is antenna 2 minus antenna 1. When a file records no frame, hyperdrive checks the stored UVWs' sign (see below); --convention casa (IAU polarisations in the hyperdrive frame) overrides that.

The oskar frame is what OSKAR uses with its default use_casa_phase_convention: nothing is precessed - the sky-model coordinates are taken as apparent coordinates of date and the array is rotated with the apparent sidereal time - and a baseline is antenna 1 minus antenna 2.

With --convention lofar, vis-simulate reproduces a DP3 predict of the same sky model on a LOFAR-like array to 1 part in 104 (DP3's own single-precision level), including an 80 km baseline, with no reordering or conjugation.

How files record conventions

Marlu's Measurement Set and uvfits writers (and so every hyperdrive output) record the conventions the visibilities were made in, using each format's own metadata where it has some:

whatMeasurement SetuvfitsUVH5
X orientationFEED table RECEPTOR_ANGLE (east is X at 90°: [π/2, 0]; north is [0, π/2])AIPS AN POLAA/POLAB (degrees)feed_angle (same angles; x_orientation is derived from them)
Stokes conventionmain-table keyword pyuvdata_polconv (avg or sum)primary-header keyword POLCONVpol_convention
UVW frameUVW column MEASINFO reference (J2000, or APP when not precessing) and marlu_uvw_framemarlu_uvw_frameuvw_array is antenna 2 minus antenna 1 (the casacore frame's sign)
baseline signthe frame's; main-table keyword pyuvdata_flip_conj is false for antenna 2 minus antenna 1 (casacore), true otherwisealways antenna 1 minus antenna 2; casacore-frame visibilities are written conjugatedantenna 2 minus antenna 1
antenna mountANTENNA MOUNT phasedAIPS AN MNTSTA 6 (phased)mount_type phased

The feed angles, mount, Stokes keyword and pyuvdata_flip_conj are exactly what pyuvdata reads and writes, so files made by either are understood by the other: a point source simulated by hyperdrive in either frame, as MS or uvfits, reads into pyuvdata with UVWs matching pyuvdata's own and phases up coherently on the source. Without pyuvdata_flip_conj, pyuvdata takes any Measurement Set it did not write as antenna 1 minus antenna 2 and would conjugate a casacore-frame one; it has no such keyword for uvfits, which is why uvfits files always use the AIPS sign. The phased mount matters because pyuvdata measures an alt-az antenna's feed angles from the parallactic angle, but a phased array's from north. The rest of the UVW frame (sidereal time, aberration, precession) is the one thing no format can express; marlu_uvw_frame (a table keyword in a Measurement Set, a HIERARCH keyword in a uvfits primary header) is hyperdrive, casacore, oskar or cotter. Note that cotter recorded the IAU feed angles ([0, π/2]) for MWA data even though the MWA's X is east-west.

When reading, hyperdrive works out the input data's conventions in this order and prints the result:

  • X orientation: from the recorded feed angles (X within 45° of east is east-west; pyuvdata is stricter and only names an orientation when both angles are exactly [π/2, 0] or [0, π/2]), except that MWA data (a metafits was given, the MS has an MWA_TILE_POINTING table, or the uvfits TELESCOP is MWA) are east-west unless the file was written by something that records conventions (it has a Stokes-convention or UVW-frame keyword, or pyuvdata's pyuvdata_has_feed), because cotter, Birli and earlier hyperdrive wrote the IAU angles for MWA data. Non-MWA data with no feed angles are north-south.
  • Stokes convention: the pyuvdata_polconv (MS) or POLCONV (uvfits) keyword, else avg.
  • UVW frame: the marlu_uvw_frame keyword; else, when the first cross-correlation's UVWs could be compared against the antenna positions, casacore if they have the antenna 2 minus antenna 1 sign; else hyperdrive for MWA data; else whichever of hyperdrive (precessed) and oskar (unprecessed) the first cross-correlation's UVWs match, when they clearly match one (the two differ by about 0.35° in 2026, metres on a kilometre baseline); else oskar if OSKAR wrote the MS (OSKAR names itself, OSKAR <version>, as the OBSERVATION table's TELESCOPE_NAME and the HISTORY table's APPLICATION; a PHASED_ARRAY table alone isn't enough, as other measurement sets made for EveryBeam, e.g. of real SKA-Low data, have one too); else hyperdrive when the sign matched, or the format's own convention (casacore for an MS, hyperdrive for uvfits) when it could not be checked. In a Measurement Set, a keyword that contradicts the UVW sign is used, with a warning. In a uvfits file the keyword alone decides the frame, as the stored sign is always antenna 1 minus antenna 2.

Input visibilities are never conjugated to change their frame; a file in the casacore frame is modelled in the casacore frame instead. (Earlier versions of hyperdrive conjugated such data on input.) hyperdrive's baselines always have the lower-numbered antenna first, so a Measurement Set row stored as ANTENNA1 > ANTENNA2 is read as the (ANTENNA2, ANTENNA1) baseline by taking its conjugate transpose (conjugating, and swapping XY and YX). This is the same visibility in the same frame, not a change of convention; such rows can be mixed with ANTENNA1 < ANTENNA2 rows. The UVW sign check uses the first cross-correlation row's own antenna order, so a reversed row there doesn't change the detected frame. The one exception to never conjugating is a uvfits file whose recorded frame has the other baseline sign from the stored UVWs (a casacore-frame uvfits written by Marlu): its cross-correlations are conjugated as they are read, undoing what the writer did. vis-convert carries the input's conventions through to its outputs.