Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Currently still in heavy development, but is able to perform direction-independent calibration on the a GPU or CPU.

More documentation: https://github.com/MWATelescope/mwa_hyperdrive/wiki

...

hyperdrive prefers to use the FEE beam when its applicable.  The associated beam code (hyperbeam) requires that the MWA FEE beam file be available at runtime; this is either done manually with a command-line argument to hyperdrive, or with the MWA_BEAM_FILE environment variable.  garrawarla users typically don't need to worry about this, because hyperdrive modules automatically set MWA_BEAM_FILE.

...

The following is current as of 4 November 202121 February 2022.

See help text:

Code Block
languagebash
themeMidnight
hyperdrive -h # -h could also be --help

...

Code Block
languagetext
themeMidnight
titleExample help output
collapsetrue
hyperdrive 0.2.0-alpha4alpha9
https://github.com/MWATelescope/mwa_hyperdrive
Calibration software for the Murchison Widefield Array (MWA) radio telescope

USAGE:
    hyperdrive <SUBCOMMAND>

FLAGSOPTIONS:
    -h, --help       PrintsPrint help information
    -V, --version    PrintsPrint version information

SUBCOMMANDS:
    di-calibrate         Perform direction-independent calibration on the input MWA data. See for more
  simulate-vis       Simulate visibilities of a sky-model source list     srclist-by-beam    Reduce a sky-model source list to the top N brightest sources, given pointing informationinfo: https://github.com/MWATelescope/mwa_hyperdrive/wiki/Calibration-usage
    simulate-vis         srclist-convertSimulate visibilities  of Convert a sky-model source list
from one format to anothersolutions-convert    Convert srclist-shiftbetween calibration solution file formats
 Shift the sources insolutions-plot a source list. Useful to correct forPlot thecalibration ionosphere.solutions
The shifts must be srclist-by-beam      Reduce a sky-model source list to the top N brightest sources, given pointing
    detailed in a .json file, with source names as keys associated with an "ra" and "dec" in     information
    srclist-convert      Convert a sky-model source list from one format degrees.to Onlyanother
the sources specified in thesrclist-shift .json are written to the output source list
    srclist-verify     Verify that sky-model source lists can be read by hyperdrive Shift the sources in a source list. Useful to correct for the ionosphere. The
                dipole-gains       Print information onshifts themust dipolebe gainsdetailed listed byin a metafits.json file, with source names as helpkeys associated with
            Prints this message or the help of the given subcommand(s) 

hyperdrive is broken up into many subcommands. Each of these have their own help; e.g.

Code Block
languagetext
themeMidnight
titleExample help output for hyperdrive simulate-vis
collapsetrue
hyperdrive-simulate-vis 0.2.0-alpha4 Simulate visibilitiesan of"ra" a sky-model source list

USAGE:
    hyperdrive simulate-vis [FLAGS] [OPTIONS] --metafits <metafits> --source-list <source-list>

FLAGS:and "dec" in degrees. Only the sources specified in the .json are written
               --no-beam          to the output source list
Should we use a beam?srclist-verify Default is to use the FEE beamVerify that sky-model source lists can be read  --unity-dipole-gainsby hyperdrive
   Pretend thatdipole-gains all MWA dipoles are alive and well, ignoring whateverPrint isinformation inon the metafitsdipole gains listed by a metafits                            file
file


hyperdrive is broken up into many subcommands. Each of these have their own help; e.g.

Code Block
languagetext
themeMidnight
titleExample help output for hyperdrive di-calibrate
collapsetrue
hyperdrive-di-calibrate 0.2.0-alpha9
Perform direction-independent calibration on the input MWA data. See for more info:
https://github.com/MWATelescope/mwa_hyperdrive/wiki/Calibration-usage

USAGE:
    hyperdrive di-calibrate [OPTIONS] [--dont-convert-lists ] [ARGUMENTS_FILE]

ARGS:
Don't attempt to convert "list" flux densities to power law flux densities. See for more
           <ARGUMENTS_FILE>    All of the arguments to di-calibrate may be specified in a toml or json file. Any CLI arguments
                     info: https://github.com/MWATelescope/mwa_hyperdrive/wiki/Source-lists  override parameters set in the file

--filter-pointsOPTIONS:
    -v, --verbosity   Don't includeThe pointverbosity componentsof from the inputprogram. skyIncrease modelby specifying multiple       --filter-gaussians      Don't include Gaussian components from the input sky modeltimes (e.g. -vv). The default is to print
                 --filter-shapelets      Don't include shapelet components from the input sky modelonly high-level information
          -v, -dry-verbosityrun      Don't actually do calibration; just verify that Thearguments verbositywere ofcorrectly theingested program.and Theprint default is to print out high-level
information         --dry-run              level Don'tinformation
actually do any work; just verify that the input arguments were correctly ingested
   -h, --help         Print help information
    -V, --version      Print version information

INPUT FILES:
    -d, --data <DATA>...     and print out high-level information         --cpu       Paths to input data files to be calibrated. These can include a Usemetafits thefile,
CPU for visibility generation. This is deliberately made non-default because                                 using a GPU is much faster  gpubox files, mwaf -hfiles, --helpa measurement set and/or uvfits files
    -s,   --source-list <SOURCE_LIST>     Prints help information     -V, --version Path to the sky-model source list file
       Prints version information

OPTIONS:
    -s, --source-list <source-list>type <SOURCE_LIST_TYPE>    The type of sky-model source list. Valid types are: hyperdrive, rts, woden,
 Path to the sky-model source list used for simulation     -m, --metafits <metafits>                      Path to the metafits file     -o, --output-model-file <output-model-file>    Path to the output visibilities file [default: model.uvfits]
    -r, --ra <ra> ao. If not specified, all types are attempted

OUTPUT FILES:
    -o, --outputs <OUTPUTS>...
            ThePaths phaseto centrethe rightcalibration ascensionoutput [degrees]files. Supported If this is not specified, then the metafits phase/pointingcalibrated visibility outputs: uvfits. Supported calibration
            solution formats: fits, bin. centre is usedDefault: hyperdrive_solutions.bin

    -dm, --dec <dec>model-filename <MODEL_FILENAME>
            The phase centre declination [degrees] path to the file where the generated sky-model visibilities are written. If this isargument notisn't specifiedsupplied, then
the metafits phase/pointing centre is        no file is written.  usedSupported formats: uvfits

       -c, --numignore-fine-channels <num-fine-channels>autos
            When Thewriting totalout numbercalibrated of fine channels in the observation [default: 384]visibilities, don't include auto-correlations

        -f, -output-freqvis-res <freqtime-res> average <OUTPUT_VIS_TIME_AVERAGE>
            When writing out calibrated visibilities, average this many The fine-channel resolution [kHz] [default: 80]
timesteps together. Also supports a target time
       --middle-freq <middle-freq>    resolution (e.g. 8s). The value must be a multiple Theof middlethe frequencyinput ofdata's the simulation [MHz]time resolution. IfThe thisdefault is notto specified,preserve
then the middle frequency specified        the input data's time  inresolution. e.g. If the input metafitsdata is used
    -t, --num-timesteps <num-timesteps> in 0.5s resolution and this variable is 4, then we
            average The2s numberworth of calibrated timedata stepstogether usedbefore fromwriting the metafitsdata epoch [default: 14]

    out. If the variable is instead 4s, then 8
   --time-res <time-res>        calibrated timesteps are averaged together before writing the data out

   The time resolution [seconds] [default: 8]
 --output-vis-freq-average <OUTPUT_VIS_FREQ_AVERAGE>
       --beam-file <beam-file>    When writing out calibrated visibilities, average this many fine Thefreq. path to the HDF5 MWA FEE beam file. If not specified, thischannels together. Also supports a target
            freq. resolution (e.g. 80kHz). The value must be provideda multiple byof the MWA_BEAM_FILE
      input data's freq. resolution. The default is to
     environment variable      preserve the  --dipole-delays <dipole-delays>...
      input data's freq. resolution. e.g. If the input data is in 40kHz resolution and this variable is 4,
     Specify the MWA dipoles delays, ignoring whatever is in the metafits file

DI calibration

Available with hyperdrive di-calibrate

Two main things are required to calibrate visibilities:

  • A data container (e.g. measurement set); and
  • A sky-model source list.

Discussion on the source lists and the applicable formats can be found here.

By default, hyperdrive will attempt to use all sources in the source list file.  If there are more than 1,000 sources in the file, then it may take a long time if you're not using a GPU.  In order to keep the number of sources used low, one could use the -n/--num-sources and/or --veto-threshold flags, or use a source list with fewer sources in the first place (see hyperdrive srclist-by-beam).

Example slurm script for garrawarla:

Code Block
languagebash
themeMidnight
#!/bin/bash -l
#SBATCH --job-name=hyp-$1
#SBATCH --output=hyperdrive.out
#SBATCH --nodes=1
#SBATCH --ntasks-per-node=40
#SBATCH --time=01:00:00
#SBATCH --clusters=garrawarla
#SBATCH --partition=gpuq
#SBATCH --account=mwaeor
#SBATCH --export=NONE
#SBATCH --gres=tmp:50g
#SBATCH --gres=gpu:1

module use /pawsey/mwa/software/python3/modulefiles
module load hyperdrive

set -eux
which hyperdrive

cd /astro/mwaeor/MWA/data/1090008640

if [[ ! -r srclist_1000.yaml ]]; then
   hyperdrive srclist-by-beam -n 1000 -m *.metafits /pawsey/mwa/software/python3/srclists/master/srclist_pumav3_EoR0aegean_fixedEoR1pietro+ForA_phase1+2.txt srclist_1000.yaml
fi

hyperdrive di-calibrate -s srclist_1000.yaml -d *.ms *.metafits       then we average 160kHz worth of calibrated data together before writing the data out. If the variable is instead
            80kHz, then 2 calibrated fine freq. channels are averaged together before writing the data out

SKY-MODEL SOURCES:
    -n, --num-sources <NUM_SOURCES>
            The number of sources to use in the source list. The default is to use them all. Example: If 1000 sources are
            specified here, then the top 1000 sources are used (based on their flux densities after the beam attenuation)
            within the specified source distance cutoff

        --source-dist-cutoff <SOURCE_DIST_CUTOFF>
            Specifies the maximum distance from the phase centre a source can be [degrees]. Default: 50

        --veto-threshold <VETO_THRESHOLD>
            Specifies the minimum Stokes XX+YY a source must have before it gets vetoed [Jy]. Default: 0.01

BEAM:
        --beam-file <BEAM_FILE>    The path to the HDF5 MWA FEE beam file. If not specified, this must be provided by the
                                   MWA_BEAM_FILE environment variable
        --unity-dipole-gains       Pretend that all MWA dipoles are alive and well, ignoring whatever is in the metafits file
        --delays <DELAYS>...       If specified, use these dipole delays for the MWA pointing
        --no-beam                  Don't apply a beam response when generating a sky model. The default is to use the FEE beam

CALIBRATION:
    -t, --time-average-factor <TIME_AVERAGE_FACTOR>
            The number of time samples to average together during calibration. Also supports a target time resolution (e.g.
            8s). If this is 0, then all data are averaged together. Default: 0. e.g. If this variable is 4, then we produce
            calibration solutions in timeblocks with up to 4 timesteps each. If the variable is instead 4s, then each timeblock
            contains up to 4s worth of data

    -f, --freq-average-factor <FREQ_AVERAGE_FACTOR>
            The number of fine-frequency channels to average together before calibration. If this is 0, then all data is
            averaged together. Default: 1. e.g. If the input data is in 20kHz resolution and this variable was 2, then we
            average 40kHz worth of data into a chanblock before calibration. If the variable is instead 40kHz, then each
            chanblock contains upto 40kHz worth of data

        --timesteps <TIMESTEPS>...
            The timesteps to use from the input data. The timesteps will be ascendingly sorted for calibration. No duplicates
            are allowed. The default is to use all unflagged timesteps

        --uvw-min <UVW_MIN>
            The minimum UVW length to use. This value must have a unit annotated. Allowed units: λ, kλ, l, kl, lambda, klambda,
            m, km. Default: 50λ

        --uvw-max <UVW_MAX>
            The maximum UVW length to use. This value must have a unit annotated. Allowed units: λ, kλ, l, kl, lambda, klambda,
            m, km. No default.

        --max-iterations <MAX_ITERATIONS>
            The maximum number of times to iterate when performing "MitchCal". Default: 50

        --stop-thresh <STOP_THRESH>
            The threshold at which we stop iterating when performing "MitchCal". Default: 1e-8

        --min-thresh <MIN_THRESH>
            The minimum threshold to satisfy convergence when performing "MitchCal". Even when this threshold is exceeded,
            iteration will continue until max iterations or the stop threshold is reached. Default: 1e-4

        --array_longitude <ARRAY_LONGITUDE_DEG>
            The Earth longitude of the instrumental array [degrees]. Default (MWA): 116.67081523611111°

        --array_latitude <ARRAY_LATITUDE_DEG>
            The Earth latitude of the instrumental array [degrees]. Default (MWA): -26.703319405555554°

        --cpu
            Use the CPU for visibility generation. This is deliberately made non-default because using a GPU is much faster

FLAGGING:
        --tile-flags <TILE_FLAGS>...
            Additional tiles to be flagged. These values correspond to either the values in the "Antenna" column of HDU 2 in
            the metafits file (e.g. 0 3 127), or the "TileName" (e.g. Tile011)

        --ignore-input-data-tile-flags
            If specified, pretend that all tiles are unflagged in the input data

        --ignore-input-data-fine-channel-flags
            If specified, pretend all fine channels in the input data are unflagged

        --fine-chan-flags-per-coarse-chan <FINE_CHAN_FLAGS_PER_COARSE_CHAN>...
            The fine channels to be flagged in each coarse channel. e.g. 0 1 16 30 31 are typical for 40 kHz data. If this is
            not specified, it defaults to flagging 80 kHz (or as close to this as possible) at the edges, as well as the centre
            channel for non-MWAX data

        --fine-chan-flags <FINE_CHAN_FLAGS>...
            The fine channels to be flagged across the whole observation band. e.g. 0 767 are the first and last fine channels
            for 40 kHz data

RAW MWA DATA:
        --pfb-flavour <PFB_FLAVOUR>     The 'flavour' of poly-phase filter bank corrections applied to raw MWA data. The
                                        default is 'empirical'. Valid flavours are: empirical, levine, none
        --no-digital-gains              When reading in raw MWA data, don't apply digital gains
        --no-cable-length-correction    When reading in raw MWA data, don't apply cable length corrections. Note that some data
                                        may have already had the correction applied before it was written
        --no-geometric-correction       When reading in raw MWA data, don't apply geometric corrections. Note that some data
                                        may have already had the correction applied before it was written

USER INTERFACE:
        --no-progress-bars    When reading in visibilities and generating sky-model visibilities, don't draw progress bars


DI calibration

Available with hyperdrive di-calibrate

Two main things are required to calibrate visibilities:

  • Raw data (gpubox files or MWAX ch??? files) or data container (measurement set or uvfits); and
  • A sky-model source list.

Discussion on the source lists and the applicable formats can be found here.

By default, hyperdrive will attempt to use all sources in the source list file.  If there are more than 1,000 sources in the file, then it may take a long time if you're not using a GPU.  In order to keep the number of sources used low, one could use the -n/--num-sources and/or --veto-threshold flags, or use a source list with fewer sources in the first place (see hyperdrive srclist-by-beam).

Example slurm script for garrawarla:

Code Block
languagebash
themeMidnight
#!/bin/bash -l
#SBATCH --job-name=hyp-$1
#SBATCH --output=hyperdrive.out
#SBATCH --nodes=1
#SBATCH --ntasks-per-node=40
#SBATCH --time=01:00:00
#SBATCH --clusters=garrawarla
#SBATCH --partition=gpuq
#SBATCH --account=mwaeor
#SBATCH --export=NONE
#SBATCH --gres=tmp:50g
#SBATCH --gres=gpu:1

module use /pawsey/mwa/software/python3/modulefiles
module load hyperdrive

set -eux
which hyperdrive

cd /astro/mwaeor/MWA/data/1090008640

# Make a source list if it isn't already there
if [[ ! -r srclist_1000.yaml ]]; then
   hyperdrive srclist-by-beam -n 1000 -m *.metafits \
              /pawsey/mwa/software/python3/srclists/master/srclist_pumav3_EoR0aegean_fixedEoR1pietro+ForA_phase1+2.txt \
              srclist_1000.yaml
fi

hyperdrive di-calibrate -s srclist_1000.yaml -d *gpubox*.fits *.metafits

Writing out calibrated visibilities

hyperdrive can write out calibrated visibilities, but only what was read in for calibration.  This means that any omitted timesteps are also omitted in the output.  Soon, a solutions-apply subcommand will allow any solutions file to be applied to any input data.

The output calibrated visibilities can also be averaged in time and frequency (by multiples of the input resolution or to a target quantity).

Code Block
languagebash
themeMidnight
titleWriting out calibrated visibilities
# Write solutions to "hyp_sols.fits" and calibrated vis to "hyp_cal.uvfits"
hyperdrive di-calibrate -s srclist_1000.yaml \
						-d *gpubox*.fits *.metafits \
						-o hyp_sols.fits hyp_cal.uvfits \
						--output-vis-time-average 2 \
						--output-vis-freq-average 80kHz


Plotting calibration solutions

Any DI solutions files that are compatible with hyperdrive (André's output from calibrate and RTS) can be plotted directly with hyperdrive.  If using a supercomputer, there's no need to run the job in the queue; it's fast enough to just run it on the login node. It's also good to plot with the corresponding metafits file to get more information:

Code Block
languagebash
themeMidnight
hyperdrive solutions-plot -m *.metafits hyp_sols.fits


If you want to do more analysis with Python, this code reads and plots the hyperdrive format:

Code Block
languagepy
themeMidnight
titlePython plotting code
collapsetrue
#!/usr/bin/env python

import sys
import numpy as np
from astropy.io import fits
import matplotlib.pyplot as plt

if len(sys.argv) == 1:
    filename = "hyp_sols.fits"
else:
    filename = sys.argv[1]

f = fits.open(filename)
data = f[1].data
# Only looking at the first timeblock.
i_timeblock = 0
data = data[i_timeblock, :, :, ::2] + data[i_timeblock, :, :, 1::2] * 1j

# Uncomment if you want to divide by a reference.
# i_tile_ref = -1
# refs = []
# for ref in data[i_tile_ref].reshape((-1, 2, 2)):
#     refs.append(np.linalg.inv(ref))
# refs = np.array(refs)
# j_div_ref = []
# for tile_j in data:
#     for (j, ref) in zip(tile_j, refs):
#         j_div_ref.append(j.reshape((2, 2)).dot(ref))
# data = np.array(j_div_ref).reshape(data.shape)

# Amps
amps = np.abs(data)

_, ax = plt.subplots(8, 16, sharex=True, sharey=True)
# Uncomment if you want to manually set the y-limit
# ax[0, 0].set_ylim(0, 2)
for i in range(128):
    ax[i // 16, i % 16].plot(amps[i, :, 0].flatten())  # XX
    ax[i // 16, i % 16].plot(amps[i, :, 3].flatten())  # YY
plt.show()

# Phases
phases = np.rad2deg(np.angle(data))

_, ax = plt.subplots(8, 16, sharex=True, sharey=True)
ax[0, 0].set_ylim(-180, 180)
for i in range(128):
    ax[i // 16, i % 16].plot(phases[i, :, 0].flatten())  # XX
    ax[i // 16, i % 16].plot(phases[i, :, 3].flatten())  # YY
plt.show()


Planned features

As hyperdrive is still in heavy development, not all features are currently available.  An indication of what is available is below.

...