run_woden.py

This is the main WODEN executable. It takes command line arguments, creates and array layout, visibility containers, read sky models, and launches GPU code to calculate the visibilities. Finally, it writes the outputs to uvfits files.

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] [--IAU_order IAU_ORDER]
                    --cat_filename CAT_FILENAME
                    [--metafits_filename METAFITS_FILENAME]
                    [--output_uvfits_prepend OUTPUT_UVFITS_PREPEND]
                    [--sky_crop_components] [--sky_crop_sources] [--do_autos]
                    [--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.703319405555554

Default: -26.703319405555554

--longitude

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

Default: 116.67081523611111

--array_height

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

Default: 377.827

--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)

• MWA_FEE_interp (MWA fully embedded element model that has had)

  spherical harmonics interpolated over frequency

• Gaussian (Analytic symmetric Gaussian)

  see –gauss_beam_FWHM and and –gauss_beam_ref_freq for

fine control)

• EDA2 (Analytic dipole with a ground mesh)

• MWA_analy (MWA analytic model)

• none (Don’t use a primary beam at all)

Defaults to –primary_beam=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: 20

--gauss_beam_ref_freq

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

Default: 150000000.0

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

--IAU_order

NEW IN WODEN versions >= 1.4.0. By default, the XX pol is now from the East-West aligned dipoles. Add –IAU_order to define the XX pol as North-South. Background: the first polaristaion output in the uvfits is called “XX”. The IAU defines “XX” as aligned to North-South, however typically it is assumed that “XX” in a uvfits is from the East-West dipoles. Le sigh. For WODEN versions < 1.4.0, XX was always the N-S dipoles.

Default: False

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

This option is deprecated, but held here for compatibility.

Default: True

--sky_crop_sources

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

Default: False

--do_autos

By default, WODEN only calculates cross-correlations. Add this flag to include auto-correlations.

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 1e10

Default: 10000000000.0

--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 run the GPU WODEN code. Author: J.L.B. Line

run_woden.main(argv=None)

Runs the WODEN simulator, given command line inputs. Does fancy things like reading in the sky model and running the GPU code in parallel; the sky model lazy load allows us to simulate sky models that cannot fit into RAM.

Parameters:

argv (_type_, optional) – Will be parsed from the command line if run in main script. Can be passed in explicitly for easy testing

run_woden.read_skymodel_thread(the_queue: Queue, chunked_skymodel_maps: list, max_num_chunks: int, lsts: ndarray, latitude: float, args: Namespace, beamtype: int)

Reads a chunked skymodel map and puts the resulting source catalogue into a queue.

Parameters:

• the_queue (Queue) – A queue to put the resulting source catalogue into.

• chunked_skymodel_maps (list) – A list of chunked skymodel maps to read.

• max_num_chunks (int) – The maximum number of chunks to read at once.

• lsts (np.ndarray) – An array of LST values.

• latitude (float) – The latitude of the observation.

• args (argparse.Namespace) – An argparse namespace containing command line arguments.

• beamtype (int) – The type of beam to use.

run_woden.woden_thread(the_queue: Queue, run_woden, woden_settings: Woden_Settings_Float | Woden_Settings_Double, visibility_set: Visi_Set_Float | Visi_Set_Double, array_layout: Array_Layout, sbf: ndarray)

This function runs WODEN C/CUDA code on a separate thread, processing source catalogues from a queue until the queue is empty.

Parameters:

• the_queue (Queue) – A queue of source catalogues to be processed.

• run_woden (_NamedFuncPointer) – A pointer to the WODEN function to be run.

• woden_settings (Union[Woden_Settings_Float, Woden_Settings_Double]) – The WODEN settings to be used.

• visibility_set (Union[Visi_Set_Float, Visi_Set_Double]) – The visibility set to write outputs to.

• array_layout (Array_Layout) – The array layout to be used.

• sbf (np.ndarray) – The shapelet basis function array