run_woden.py

This is the main way to control the WODEN executable, and ensure good arguments are supplied. I suggest you only run WODEN through this script.

Command line running options

Run the WODEN simulator and profit. WODEN is setup to simulate MWA-style observations, where the full frequency bandwidth is split into 24 ‘coarse’ bands, each of which is split into fine channels. This naturally allows any simulation to be split across multiple GPUs as separate processes.

usage: run_woden.py [-h] [--band_nums BAND_NUMS]
                    [--lowest_channel_freq LOWEST_CHANNEL_FREQ]
                    [--coarse_band_width COARSE_BAND_WIDTH]
                    [--num_freq_channels NUM_FREQ_CHANNELS]
                    [--freq_res FREQ_RES] [--num_time_steps NUM_TIME_STEPS]
                    [--time_res TIME_RES] --ra0 RA0 --dec0 DEC0 [--date DATE]
                    [--no_precession] [--latitude LATITUDE]
                    [--longitude LONGITUDE] [--array_height ARRAY_HEIGHT]
                    [--array_layout ARRAY_LAYOUT]
                    [--primary_beam PRIMARY_BEAM]
                    [--gauss_beam_FWHM GAUSS_BEAM_FWHM]
                    [--gauss_beam_ref_freq GAUSS_BEAM_REF_FREQ]
                    [--gauss_ra_point GAUSS_RA_POINT]
                    [--gauss_dec_point GAUSS_DEC_POINT]
                    [--hdf5_beam_path HDF5_BEAM_PATH]
                    [--MWA_FEE_delays MWA_FEE_DELAYS]
                    [--telescope_name TELESCOPE_NAME] --cat_filename
                    CAT_FILENAME [--metafits_filename METAFITS_FILENAME]
                    [--output_uvfits_prepend OUTPUT_UVFITS_PREPEND]
                    [--sky_crop_components] [--precision PRECISION]
                    [--remove_phase_tracking] [--no_tidy]
                    [--chunking_size CHUNKING_SIZE] [--dry_run]

FREQUENCY OPTIONS

--band_nums

Defaults to running 24 coarse bands. Alternatively, enter required numbers delineated by commas, e.g. –band_nums=1,7,9

Default: “all”

--lowest_channel_freq

Set the frequency (Hz) of the lowest channel for band 1. If using a metafits file, this will override the frequency in the metafits

Default: False

--coarse_band_width

Set the width of each coarse band If using a metafits file, this will override the frequency in the metafits

Default: 1280000.0

--num_freq_channels

Number of fine frequency channels to simulate - defaults to –coarse_band_width / –freq_res

Default: “obs”

--freq_res

Fine channel frequnecy resolution (Hz) - will default to what is in the metafits

Default: False

TIME OPTIONS

--num_time_steps

The number of time steps to simualte. Defaults to how many are inthe metafits if using metafits

Default: False

--time_res

Time resolution (s) - will default to what is in the metafits if the metafits if using metafits

Default: False

OBSERVATION OPTIONS

--ra0

RA of the desired phase centre (deg)

--dec0

Dec of the desired phase centre (deg)

--date

Initial UTC date of the observatio in format YYYY-MM-DDThh:mm:ss This is used to set the LST and array precession. This is set automatically when reading a metafits but including this will override the date in the metafits

Default: False

--no_precession

By default, WODEN rotates the array back to J2000 to match the input sky catalogue. Add this to switch off precession

Default: False

TELESCOPE OPTIONS

--latitude

Latitude (deg) of the array - defaults to MWA at -26.7033194444

Default: -26.7033194444

--longitude

Longitude (deg) of the array - defaults to MWA at 116.670813889

Default: 116.670813889

--array_height

Height (m) of the array above sea level - defaults to MWA at 377.0

Default: 377.0

--array_layout

Instead of reading the array layout from the metafits file, read from a text file. Store antenna positions as offset from array centre, in east, north, height coords (metres)

Default: False

--primary_beam

R|Which primary beam to use in the simulation. Options are:

MWA_FEE (MWA fully embedded element model) Gaussian (Analytic symmetric Gaussian)

see –gauss_beam_FWHM and and –gauss_beam_ref_freq for

fine control)

EDA2 (Analytic dipole with a ground mesh) none (Don’t use a primary beam at all)

Defaults to none

Default: “none”

--gauss_beam_FWHM

The FWHM of the Gaussian beam in deg - WODEN defaults to using 20 deg if this is not set

Default: False

--gauss_beam_ref_freq

The frequency at which the gauss beam FWHM is set at. If not set, WODEN will default to 150MHz.

Default: False

--gauss_ra_point

The initial RA (deg) to point the Gaussian beam at. This will be used to calculate an hour angle at which the beam will remain pointed at for the duration of the observation. Defaults to the RA of the metafits if available, or the RA of the phase centre if not

Default: False

--gauss_dec_point

The initial Dec (deg) to point the Gaussian beam at. Defaults to the Dec of the metafits if available, or the Dec of the phase centre if not

Default: False

--hdf5_beam_path

Location of the hdf5 file holding the FEE beam coefficients

Default: False

--MWA_FEE_delays

R|A list of 16 delays to point the MWA FEE primary beam model enter as as list like: –MWA_FEE_delays=[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0] for a zenith pointing. This is read directly from the metafits if using a metafits file

Default: False

--telescope_name

Name of telescope written out to the uvfits file, defaults to MWA

Default: “MWA”

INPUT/OUTPUT OPTIONS

--cat_filename

Path to WODEN style sky model

--metafits_filename

MWA style metafits file to base the simulation on. Array layout, frequency and time parameters are all set by this option, but can be overridden using other arguments

Default: False

--output_uvfits_prepend

Prepend name for uvfits - will append band%02d.uvfits %band_num at the end. Defaults to “output”.

Default: “output”

--sky_crop_components

WODEN will crop out sky model information that is below the horizon for the given LST. By default, for each SOURCE in the sky model, if any COMPONENT is below the horizon, the entire source will be flagged. If –sky_crop_components is included WODEN will include any COMPONENT above the horizon, regardless of which SOURCE it belongs to.

Default: False

SIMULATOR OPTIONS

--precision

What precision to run WODEN at. Options are “double” or “float”. Defaults to “double”

Default: “double”

--remove_phase_tracking

By adding this flag, remove the phase tracking of the visibilities - use this to feed uvfits into the RTS

Default: False

--no_tidy

Defaults to deleting output binary files from woden and json files. Add this flag to not delete those files

Default: False

--chunking_size

The chunk size to break up the point sources into for processing - defaults to 0 (use default chunking in WODEN)

Default: False

--dry_run

Add this to NOT call the WODEN executable - this will just write out the .json file and do nothing else

Default: False

Function documentation

Wrapper script to generate json input files for, and to run, the GPU WODEN code. Author: J.L.B. Line

run_woden.RTS_decode_baseline(blcode)[source]

The ancient aips/miriad extended way of decoding a baseline. Takes the baseline code from the ‘BASELINE’ array of a uvfits, and returns the index of antennas 1 and 2 that form the baseline.

Parameters

blcode (int) – Baseline code from a uvfits file encoded the two antennas

Returns

  • b1 (int) – Index of first antenna

  • b2 (int) – Index of second antenna

run_woden.RTS_encode_baseline(b1, b2)[source]

The ancient aips/miriad extended way of encoding a baseline by antenna number, by multiplying antenna number 1 by 256, and adding the second antenna number. (e.g. b1*256 + b2). Needed for populating the uvfits files.

Uses the RTS extension for antennas higher that 255, where encoding happens as b1*2048 + b2 + 65536

Parameters

  • b1 (int) – Index of first antenna

  • b2 (int) – Index of second antenna

Returns

baseline_number – Encdoded baseline number for uvfits ‘BASELINE’ array

Return type

int

run_woden.calc_jdcal(date)[source]

Takes a string calendar date-time and returns julian date by using astropy.time.Time, so date can be formatted anyway astropy.time.Time accepts. Returns the date in two parts, an integer day, and a fractional day. The header of a uvfits file takes the integer part, and the fractional part goes into the DATE array

Parameters

date (string) – UTC date/time (e.g. in format YYYY-MM-DDThh:mm:ss or similar)

Returns

  • jd_day (float) – floor of the julian date

  • jd_fraction (float) – remaining fraction of the julian date

run_woden.check_args(args)[source]

Check that the combination of arguments parsed will work with the WODEN executable. Attempts to grab information from a metafits file if possible. Should error with helpful messages if a combination that won’t work is attempted by the user

Parameters

args (argparse.Namespace) – The populated arguments args = parser.parse_args()` as returned from the parser given by get_parser()

Returns

args – The populated arguments which will now have been checked and had information from metafits incorporated if requested

Return type

argparse.Namespacer

run_woden.command(cmd)[source]

Runs the command string cmd using subprocess.call

Parameters

cmd (string) – The command to run on the command line

run_woden.create_uvfits(v_container=None, freq_cent=None, central_freq_chan=None, ch_width=None, ra_point=None, dec_point=None, output_uvfits_name=None, uu=None, vv=None, ww=None, longitude=None, latitude=None, array_height=None, telescope_name=None, baselines_array=None, date_array=None, int_jd=None, hdu_ant=None, gitlabel=False)[source]

Takes visibility data read in from WODEN binary files, predefined BASELINE and DATE arrays and an antenna table, and writes them out together into a uvfits file. Uses multiple astropy.io.fits routines to create the final uvfits file. Uses GroupData and GroupsHDU to create the data table, and then combines with the antenna table in a uvfits via HDUList.

Parameters

  • v_container (float array) –

    Data container for the visibility data. Should have shape = (num_time_steps*num_baselines, 1, 1, num_freq_channels, 4, 3) and should contain instrumental linear polarisation visibilities. The axes should change as:

    • 1st axis: ordered by baseline (fastest changing) and then time step (slowest changing).

    • 2nd, 3rd axes: essentially do nothing in these uvfits, are placeholders

    • 4th axis: ordered with increasing frequency

    • 5th axis: ordered by polarisation in the order of XX,YY,XY,YX

    • 6th axis: ordered by real visi part, imaginary visi part, weighting

  • freq_cent (float) – Frequency of the central frequency channel (Hz)

  • central_freq_chan (int) – Index of the central frequency channel (zero indexed)

  • ch_width (float) – Resolutiom of frequency channels (Hz)

  • ra_point (float) – Right ascension of the observation, to set header keyword ‘OBSRA’ with (deg)

  • dec_point (float) – Declination of the observation, to set header keyword ‘OBSDEC’ with (deg)

  • output_uvfits_name (string) – Name for the output uvfits file

  • uu (float array) – :math`u` coordinates (seconds).

  • vv (float array) – :math`v` coordinates (seconds).

  • ww (float array) – :math`w` coordinates (seconds).

  • baselines_array (int/float array) – Baseline coding needed for ‘BASELINE’ array

  • date_array (float array) – Fractional julian date array to put in ‘DATE’ array (days)

  • int_jd (int) – Integer julian date to put in the header as ‘PZERO4’

  • hdu_ant (astropy.io.fits.hdu.table.BinTableHDU) – Populated uvfits antenna table

  • gitlabel (string) – Optional string to add as ‘GITLABEL’ in the header. Used by WODEN to add the git commit of the code for this run

run_woden.enh2xyz(east, north, height, latitude=- 0.46606084551660293)[source]

Takes local east, north, height coords for a given latitude (radians) and returns local X,Y,Z coords to put in the uvfits antenna table

Parameters

  • east (float) – Local east coorindate (metres)

  • north (float) – Local north coorindate (metres)

  • height (float) – Local height coorindate (metres)

  • latitude (float) – Latitude of the array - defaults to MWA location (radians)

Returns

  • X (float) – Local X antenna location

  • Y (float) – Local Y antenna location

  • Z (float) – Local Z antenna location

run_woden.get_parser()[source]

Runs the argument parser to get command line inputs - used by sphinx and argparse extension to unpack the help below into the online readthedocs documentation.

Returns

parser – The populated argument parser used by run_woden.py

Return type

argparse.ArgumentParser

run_woden.get_uvfits_date_and_position_constants(latitude=None, longitude=None, date=None, height=None)[source]

Returns a number of date and time based values that are needed for uvfits headers. For the given Earth location and UTC date return the local sidereal time (deg), the Greenwich sidereal time at 0 hours on the given date (deg), the rotational speed of Earth on the given date (in degrees per day), and the difference between UT1 and UTC. Uses astropy.time.Time and astropy.coordinates.EarthLocation to make the calculations.

Parameters

  • latitude (float) – Latitude of location on Earth (deg)

  • longitude (float) – Longitude of location on Earth (deg)

  • date (string) – UTC date/time (e.g. in format YYYY-MM-DDThh:mm:ss or similar)

Returns

  • LST_deg (float) – Local sidereal time (degrees)

  • GST0_deg (float) – Greenwich sidereal time at 0 hours on the given date (degrees)

  • DEGPDY (float) – Rotational speed of Earth on the given date (degrees per day)

  • ut1utc (float) – Difference between UT1 and UTC (secs)

run_woden.load_data(filename=None, num_baselines=None, num_freq_channels=None, num_time_steps=None, precision=None)[source]

Read the WODEN binary output and shove into a numpy arrays, ready to be put into a uvfits file. Data in WODEN binaries is ordered by baseline (fastest changing), frequency, and time (slowest changing). Visibility coords and data are read in, with the visi data output into an array of shape=(num_time_steps*num_baselines,1,1,num_freq_channels,4,3)), which is appropriate for a uvfits file. Needs to know whether WODEN was run with ‘float’ (32 bit) or ‘double’ (64 bit) precision to read in the data correctly.

Parameters

  • filename (string) – Name of WODEN binary file to read from

  • num_baselines (int) – Number of baselines in the binary file

  • num_freq_channels (int) – Number of frequencies in the binary file

  • num_time_steps (int) – Number of time steps in the binary file

  • precision (string) – Precision WODEN was run with - either ‘float’ or ‘double’

Returns

  • uus (float array) – The \(u\) coordinates (seconds)

  • vvs (float array) – The \(v\) coordinates (seconds)

  • wws (float array) – The \(w\) coordinates (seconds)

  • v_container (float array) – Visibility data with shape=(num_time_steps*num_baselines,1,1,num_freq_channels,4,3))

run_woden.make_antenna_table(XYZ_array=None, telescope_name=None, num_antennas=None, freq_cent=None, date=None, gst0_deg=None, degpdy=None, ut1utc=None, longitude=None, latitude=None, array_height=None)[source]

Write an antenna table for a uvfits file. This is the first table in the uvfits file that encodes antenna positions, with some header keywords. Uses astropy.io.fits.BinTableHDU to create the table.

Parameters

  • XYZ_array (float array) – Array with shape = (num_antennas, 3), containg the local \(X,Y,Z\) coorindates of the antenna locations (meters)

  • telescope_name (string) – Name to assign to the ‘ARRNAM’ header keyword

  • num_antennas (int) – Number of antennas in the array

  • freq_cent (float) – Central frequency to assign to the ‘FREQ’ header keyword (Hz)

  • date (string) – UTC date/time in format YYYY-MM-DDThh:mm:ss to give to the ‘RDATE’ header keyword

  • gst0_deg (float) – Greenwich sidereal time at 0 hours on the given date (degrees)

  • degpdy (float) – Rotational speed of Earth on the given date (degrees per day)

  • ut1utc (float) – Difference between UT1 and UTC (secs)

  • longitude (float) – Longitude of the array (deg)

  • latitude (float) – Latitude of the array (deg)

  • array_height (float) – Height of the array above sea level (metres)

Returns

hdu_ant – Populated uvfits antenna table

Return type

astropy.io.fits.hdu.table.BinTableHDU

run_woden.make_baseline_date_arrays(num_antennas, date, num_time_steps, time_res)[source]

Makes the BASELINE and DATE arrays needed in the uvfits file The BASELINE array encode which two antennas formed the baseline The DATE array contains the fractional jd date, that is added to the header value PZERO5, to specify the time each visibility was recorded at

Parameters

  • num_antennas (int) – The number of antennas in the antenna table

  • date (string) – Initial UTC date/time (e.g. in format YYYY-MM-DDThh:mm:ss or similar)

  • num_time_steps (int) – Number of time steps in the data

  • time_res (float) – Integration time of the data (seconds)

Returns

  • baselines_array (float array) – The uvfits antenna encoded array needed for BASELINE

  • date_array (float array) – The fractional part of the julian date needed for DATE (days)

run_woden.remove_phase_tracking(frequencies=None, wws_seconds=None, num_time_steps=None, v_container=None, num_baselines=None)[source]

WARNING - currently does not change the \(u,v,w\) coordinates, so they are still defined via the original phase centre. This function really is just to feed uvfits into the RTS (which generates it’s own u,v,w using the antenna table)

Undoes phase tracking applied by WODEN - to phase track, a phase was applied to counter the delay term caused by \(w\) term of baseline - so just apply the opposite effect of the w term, i.e.

\[V^\prime = V \exp(2\pi i w)\]

where \(V\) is the phase tracked visibility and \(V^\prime\) is the visibility after removing phase tracking.

Parameters

  • frequencies (float array) – Frequencies of all fine channels (Hz)

  • wws_seconds (float array) – The \(w\) coordinates (seconds)

  • num_baselines (int) – Number of baselines

  • v_container (float array) – Complex visibility data out of WODEN with phase tracking, with shape=(num_time_steps*num_baselines,1,1,num_freq_channels,4,3))

Returns

v_container – Same visibility data as before, with phase tracking returned.

Return type

float array

run_woden.select_argument_and_check(parser_arg, parser_value, metafits_arg, parser_string, do_exit=True)[source]

Some arguments taken from the argparse.parser should override settings from the metafits if present. If the parser argument parser_arg is defined (i.e. not False), update it to equal parser_value. If not defined, update parser_arg to metafits_arg, which is the value read in from the metafits file. If both parser_arg and metafits_arg are False, WODEN will fail, so exit with a message. Use parser_string to define which parser arguement has failed; this will be included in the error message.

Parameters

  • parser_arg (attribute of argparse.Namespace) – The option in args to update

  • parser_value (Expected type for parser_arg) – The value to set parser_arg to (e.g. float(parser_arg))

  • metafits_arg (Expected type for parser_arg) – The value read in from the metafits if using metafits; False if not

  • parser_string (string) – The parser option under test to be written out in the error message, e.g. “–MWA_FEE_delays”

  • do_exit (Boolean) – Whether to call sys.exit upon both parser_arg and metafits_arg being False. Defaults to True

Returns

parser_arg – The update option in args

Return type

attribute of argparse.Namespace

run_woden.select_correct_enh(args)[source]

Depending on whether we are reading the array layout from the metafits file or a text file, read in the correct amount of east,north,height coords. Sets args.east, args.north, args.height, args.num_antennas, and args.array_layout_name.

Parameters

args (argparse.Namespace) – The populated arguments args = parser.parse_args()` as returned from the parser given by get_parser()

run_woden.write_json(json_name=None, jd_date=None, lst=None, args=None)[source]

Populate and write out a .json parameter file used to run WODEN. Is later used on the command line to run WODEN.

Parameters

  • json_name (string) – Name out .json file to save outputs to

  • jd_date (float) – Initial Julian date of simulation (days)

  • lst (float) – Local sidereal time of the simulate (degrees)

  • args (argparse.Namespace) – The args as returned by check_args(), which takes the args as return by args=parser.parse_args(), from the parser returned by get_parser().