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:
--pol-conventionand--uvw-frame, if given;--convention, a preset for both;- the conventions recorded in, or implied by, the input data (see below);
- the MWA's (
vis-simulatehas 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).
--convention | polarisations | UVW frame | for |
|---|---|---|---|
mwa | mwa | hyperdrive | MWA data and hyperdrive's own outputs |
iau (alias casa) | iau | hyperdrive | IAU polarisations without the casacore frame, e.g. Measurement Sets CASA itself writes (see the note on CASA below) |
lofar | iau | casacore | LOFAR data, DP3 |
casacore (aliases wsclean, uvh5, pyuvdata) | iau | casacore | Measurement Sets whose UVWs casacore or DP3 computed; UVH5 files |
askap (alias askapsoft) | askap | casacore | ASKAPsoft |
oskar | mwa | oskar | OSKAR 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:
| what | Measurement Set | uvfits | UVH5 |
|---|---|---|---|
| X orientation | FEED 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 convention | main-table keyword pyuvdata_polconv (avg or sum) | primary-header keyword POLCONV | pol_convention |
| UVW frame | UVW column MEASINFO reference (J2000, or APP when not precessing) and marlu_uvw_frame | marlu_uvw_frame | uvw_array is antenna 2 minus antenna 1 (the casacore frame's sign) |
| baseline sign | the frame's; main-table keyword pyuvdata_flip_conj is false for antenna 2 minus antenna 1 (casacore), true otherwise | always antenna 1 minus antenna 2; casacore-frame visibilities are written conjugated | antenna 2 minus antenna 1 |
| antenna mount | ANTENNA MOUNT phased | AIPS 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 anMWA_TILE_POINTINGtable, or the uvfitsTELESCOPisMWA) are east-west unless the file was written by something that records conventions (it has a Stokes-convention or UVW-frame keyword, or pyuvdata'spyuvdata_has_feed), becausecotter,Birliand earlierhyperdrivewrote the IAU angles for MWA data. Non-MWA data with no feed angles are north-south. - Stokes convention: the
pyuvdata_polconv(MS) orPOLCONV(uvfits) keyword, elseavg. - UVW frame: the
marlu_uvw_framekeyword; else, when the first cross-correlation's UVWs could be compared against the antenna positions,casacoreif they have the antenna 2 minus antenna 1 sign; elsehyperdrivefor MWA data; else whichever ofhyperdrive(precessed) andoskar(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); elseoskarif OSKAR wrote the MS (OSKAR names itself,OSKAR <version>, as theOBSERVATIONtable'sTELESCOPE_NAMEand theHISTORYtable'sAPPLICATION; aPHASED_ARRAYtable alone isn't enough, as other measurement sets made for EveryBeam, e.g. of real SKA-Low data, have one too); elsehyperdrivewhen the sign matched, or the format's own convention (casacorefor an MS,hyperdrivefor 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.