Using schedule_observation.py
In almost all cases, observations will be scheduled by the MWA operations team, but for special cases, the PI can provide scripts (developed in collaboration with the operations team) that schedule observations directly.
The command line tool used by the operations team is called ‘schedule_observation.py’, and calling it will generate one contiguous block of observations of one or more sources. This can be a single observation, but it’s usually split into many sub-observations because MWA tiles are only pointed at the start of each sub-observation - and to reduce the download size to process.
The schedule_observation.py command has many, many possible command line arguments, but most are rarely used.
At a minimum, to schedule a simple observation, you need to specify these options:
--starttime= for the start of the observation. Values are as described below.
--stoptime= for the end of the observation. Values are as described below.
Where to point at, usually one of these three ways:
--source= by name, eg --source=Sun or --source=HerA.
--ra= and --dec= where both can be either floats or H/D:MM:SS strings. If RA is a float it's in degrees, if RA is a string, it's in HH:MM:SS hours. Dec is always in degrees.
--az= and --el= (or --alt=) Azimuth and elevation, both in degrees.
--gall= and --galb= Galactic latitude and longitude
--creator= Arbitrary string containing the username or script name running the command.
--tileset= The name of a pre-defined set of tiles to use for this observation - typically one of ‘phase_one’, ‘p2_compact’, ‘p2_compact_OS', ‘p2_extended’, ‘p1+hexes’, ‘p1+solar’ or '256T’.
--projectid= to give a project ID code (defaults to C001).
--mode= Observation mode - use either NO_CAPTURE, or MWAX_VCS, or (the default), MWAX_CORRELATOR, or, to schedule a mode switch, CORR_MODE_CHANGE (put the mode to switch to - either ‘OS’ or ‘CS’ - as the first two letters of the observation name).
--obsname= Arbitrary string with the name of the observation. The source name and frequency information will be appended automatically.
If you run it without a source name, RA/DEC or ALT/AZ, it will print out a list of common radio sources, along with their coordinates and elevation above the horizon at the --starttime that you specified.
Other common options are:
--freq= What coarse channels to use in the observation. Usually you would use something like "--freq=121,24", which means '24 course channels, centred on channel 121'.
--inttime= Correlator integration time, in seconds, eg --inttime=0.5.
--freqres= Correlator frequency resolution, in kHz, eg --freqres=10 or --freqres=0.2 (for 200 HZ).
--calibration and --calibrator= (always used together). Mark this observation as a calibrator, and provide the source name of that calibrator in the field.
--precal= and --postcal= Automatically schedule 2-minute a calibrator observation before the given target (starting at the specified starttime, not before it), and/or after the given target. You can specify the name of the calibrator to use, if you know it's above the horizon (eg --postcal=3C444) or just leave it as --precal= or --postcal= to have it choose the best calibrator to use automatically. Note that you need to include the '=' after the option, or it will have no effect.
Specifying starttime/stoptime
Both --starttime= and --stoptime= have several ways in which you can specify the time:
As a full time string, in UTC, in quotes - eg --starttime="2023-01-20,10:11:12" - the format is strict, and must be exactly as shown here.
As a time in GPS seconds - eg --starttime=1358214413
As an offset from either 'now' (when used with --starttime), or from the given or implied start time (when used with --stoptime). The offset can be in seconds (default), minutes, or hours:
--starttime=++600 (600 seconds from now)
--starttime=++1h (1 hour from now)
--starttime=++10m (10 minutes from now)
--stoptime=++86400 (24 hours from whenever the --starttime is, or from now if you didn't give a starttime)
Note that whatever time/s and durations you specify, all observations must start and finish on an integer multiple of 8 seconds in GPS time, so specifying --stoptime=++60 for example, will result in a 56 second observation.
Note also that if you specify the --precal= option (see below), the (typically) 120-second calibration exposure will be scheduled at the time specified, and the actual observations will follow. If timing is critical - for example, short observations to catch known transient pulse times - you need to account for the pre-calibrator observation time.
Using LST and date to specify observation start time
If preferred, you can use the UTC date and local sidereal time to specify when an observation should start. In this case, don’t give a --starttime or a --stoptime - instead, specify:
--utdate - the UTC day on which to schedule the observation
--lst - the local sidereal time, in hours, at which to start the observation
--exptime - how long to observe the source (this is a duration, so don’t use the leading ‘++’ you would to specify the --stoptime).
For example, to observe a source with an RA of 14.0 hours, for an hour over zenith, you would use something like:
… --utdate='2025-08-21' --lst=13.5 --exptime=3600 …
Allowing for the length of a --precal= option applies here too, so for a 120 second precal observation, subtract 0.0333 hours from the specified --lst value.
Advanced usage
You can specify as many sources as you want, in any combination of source name, ra/dec, az/el, galactic lat/long, or delay settings. Each of the sources will be observed in that order.
You can specify as many channel settings with --freq= as you want - each source you specify will be observed at each of the channel settings you specify.
You can specify the number of times each source/channelset will be specified with ‘--nobs=’. For example, for --nobs=2, if you have two sources (S1, S2) and three channel selections (C1, C2, C3), it will observe S1/C1, S1/C2, S1/C3, S2/C1, S2/C2, S2/C3, then S1/C1, S1/C2, S1/C3, S2/C1, S2/C2, S2/C3.
If you specify a --stoptime, each observation will be one N’th of the (stoptime-starttime) in duration, rounded down a multiple of 8 seconds. Usually, you would instead specify --exptime= to give the duration of each observation, at each channel setting, instead of --stoptime.
Instead of specifying a --starttime, you can give both --utdate= (as ‘YYYY-MM-DD’) and --lst= as a fractional local sidereal time, in hours, on that UT date. If you pass the same --lst= value for different dates, observations will be sidereally matched between them, and at the same gridpoints.
You can specify --avoidsun, or --avoidsource=CenA (for example) to put the Sun or the specified source in a primary beam null for each pointing. If the source to be avoided is below the horizon, this option will be ignored. Note that this won’t work well if either the pointing direction or the source to be avoided is at low elevations, and it’s calculated for the centre channel (the 13th out of 24) for the observation. There’s not much point using this option for picket fence observations.
You can point multiple non-overlapping subarrays of tiles in different directions in the same observation. To do this, run schedule_observation.py more than once, with exactly the same parameters, except:
Use --rfstream=0 for the first call, --rfstream=1 for the second call, --rfstream=2 for the third call, etc.
Specify a different, non-overlapping tile set with the --tiles option for each call.
Use a different pointing direction (with --source, --ra/dec, etc) for each call.
Full usage information
Usage: schedule_observation.py [options]
Schedules one or more observations for the MWA telescope. Required parameters include:
Starttime and Stoptime: The beginning and end of the observation block
Source coordinates: RA/Dec, Alt/Az, Galactic Lat/Long, source name, or a list of raw beamformer delays.
Observation details: Frequency, correlator mode and settings, attenuation, etc.
Constraints: Minimum elevation, Sun/Jupiter distance, use of 'sweet spot' grid positions, etc.
Metadata: Observation name, creator name, project ID code, etc
Example: schedule_observation.py --starttime=++0 --stoptime=++32 --ut --usegrid= --source=SMC --freq=121,24"
Options:
--version show program's version number and exit
-h, --help show this help message and exit
--starttime=STARTTIME
Observation start time in GPSseconds or yyyy-mm-
dd,hh:mm:ss, or ++<dt>[s/m/h] from now. Can use --date
and --lst instead
--stoptime=STOPTIME Observation stop time as above, or ++DT[s/m/h] from
starttime. If omitted, use starttime +
(nsourcesnfreqsexptime)
--groupid=GROUPID Starttime of first observation in this group (only
needed when altering an existing block). If omitted,
use starttime
--exptime=EXPTIME Time in seconds to observe each source/freqspec
combination. Rounded down to the nearest modulo 8
seconds.
--nobs=NOBS Number of times to observe each source/freqspec
combination, defaults to 1.
--utdate=UTDATE, --date=UTDATE
UT Date (YYYY-MM-DD) to schedule observation - must be
used with the --lst parameter, and WITHOUT specifying
--starttime
--lst=LST, --lsthour=LST
LST in hours to schedule observation - must be used
with the --date parameter, and WITHOUT specifying
--starttime
--obsname=OBSNAME, --name=OBSNAME
Base name of observation. Will have source name and
centre frequency channel appended.
--inttime=INT_TIME Correlator integration time (s). [default=0.5]
--freqres=FREQ_RES Correlator frequency resolution (kHz). [default=10.0]
--delaymode=DELAYMODE_NAME, --delaymode_name=DELAYMODE_NAME
MWAX delay mode, one of: ['CABLE: Apply cable delays
only\n', 'CABLEZEN: Apply cable delays and phase up to
zenith\n', 'FULLCAL: Phase up to source, with real-
time calibration\n', 'FULLCHAIN: Full fringe stopping,
with signal chain phase correction\n', 'FULLTRACK:
Phase up to track source\n', 'NODELAYS: No delays
applied\n', 'SIGCHAIN: Only signal chain phase
correction, no fringe stopping\n', 'TILEBEAM: Phase up
to primary beam pointing direction\n']
[default=FULLTRACK for normal observations, NODELAYS
for VCS]
--deripple Turn on deripple mode in the MWAX correlator
--comment=COMMENT Text comment for observation
--creator=CREATOR Name of the observation creator - default is
<user>=django, but alternative required if <user> is
mwa or root.
--project=PROJECTID, --projectid=PROJECTID
Project identifier, one of ['A0001', 'C000', 'C001',
'C002', 'C003', 'C100', 'C101', 'C102', 'C103',
'C104', 'C105', 'C106', 'C110', 'C111', 'C112',
'C113', 'C114', 'C115', 'C116', 'C117', 'C118',
'C119', 'C120', 'C121', 'C122', 'C123', 'D0000',
'D0001', 'D0002', 'D0003', 'D0004', 'D0005', 'D0006',
'D0007', 'D0008', 'D0009', 'D0010', 'D0011', 'D0012',
'D0013', 'D0014', 'D0015', 'D0016', 'D0017', 'D0018',
'D0019', 'D0020', 'D0021', 'D0022', 'D0023', 'D0024',
'D0025', 'D0026', 'D0027', 'D0028', 'D0029', 'D0030',
'D0031', 'D0032', 'D0033', 'D0034', 'D0035', 'D0036',
'D0037', 'D0038', 'D0039', 'D0040', 'D0041', 'D0042',
'D0043', 'D0044', 'D0045', 'D0046', 'D0047', 'D0048',
'D0049', 'D0050', 'D0051', 'G0001', 'G0002', 'G0003',
'G0004', 'G0005', 'G0006', 'G0008', 'G0009', 'G0010',
'G0011', 'G0012', 'G0015', 'G0016', 'G0017', 'G0018',
'G0019', 'G0020', 'G0021', 'G0022', 'G0023', 'G0024',
'G0025', 'G0026', 'G0027', 'G0028', 'G0029', 'G0030',
'G0031', 'G0032', 'G0033', 'G0034', 'G0035', 'G0036',
'G0037', 'G0038', 'G0039', 'G0040', 'G0041', 'G0042',
'G0043', 'G0044', 'G0045', 'G0046', 'G0047', 'G0048',
'G0049', 'G0050', 'G0051', 'G0052', 'G0053', 'G0054',
'G0055', 'G0056', 'G0057', 'G0058', 'G0059', 'G0060',
'G0061', 'G0062', 'G0063', 'G0064', 'G0065', 'G0066',
'G0067', 'G0068', 'G0069', 'G0070', 'G0071', 'G0072',
'G0073', 'G0074', 'G0075', 'G0076', 'G0077', 'G0078',
'G0079', 'G0080', 'G0081', 'G0082', 'G0083', 'G0084',
'G0085', 'G0086', 'G0087', 'G0088', 'G0089', 'G0090',
'G0091', 'G0092', 'G0093', 'G0094', 'G0095', 'G0096',
'G0097', 'G0098', 'G0099', 'G0100', 'G0101', 'G0102',
'G0103', 'G0104', 'G0105', 'G0106', 'G0107', 'G0108',
'G0109', 'G0110', 'G0111', 'G0112', 'G0113', 'G0114',
'G0115', 'OA001', 'OA002', 'OA003', 'OA004', 'OA005',
'OA006', 'OA007'] [default=C001]
--mode=MODE, --obsmode=MODE
Observing mode, one of ['BURST_VSIB',
'BURST_VSIB_RAW', 'BURST_VSIB_SYNCED',
'CORR_MODE_CHANGE', 'ENTER_BURST', 'ENTER_CHANNEL',
'HW_COR_PKTS', 'HW_LFILES', 'HW_LFILES_NOMENTOK',
'LFILES_CLIENT', 'MWAX_BUFFER', 'MWAX_CORRELATOR',
'MWAX_VCS', 'NO_CAPTURE', 'NO_CAPTURE_BURST',
'RTS_32T', 'SW_COR_VSIB', 'SW_COR_VSIB_NOMENTOK',
'VOLTAGE_BUFFER', 'VOLTAGE_RAW', 'VOLTAGE_START',
'VOLTAGE_STOP']. [default=MWAX_CORRELATOR]
Pointing options:
One or more sources must be specified using: SOURCE, (RA,DEC),
(ALT,AZ), (GALL,GALB), HEX
--source=SOURCENAME_LIST
Name of the source to track. It can be 'Sun' or a
planet name, a name in the local mwa_sources table, a
name in the given satellite TLE file, or looked up
online using the CDS name resolver.
--tlefile=TLE_FILENAME
Read in satellite two-line elements, either specified
by local file or URL (see
https://celestrak.com/NORAD/elements/).
--ra=RA_LIST Source to track by RA,Dec (hh:mm:ss or decimal
degrees) in ICRS reference frame.
--dec=DEC_LIST Source to track by RA,Dec (dd:mm:ss or decimal
degrees) in ICRS reference frame.
--gall=GALL_LIST Source to track by Galactic l,b (dd:mm:ss or decimal
degrees).
--galb=GALB_LIST Source to track by Galactic l,b (dd:mm:ss or decimal
degrees).
--avoidsun Modify the pointing to put the Sun in a beam null, but
keep the given source coordinate as close as possible
to the beam centre.Only works if source name or
ra/dec/gall/galb used for target coordinates, not
az/el.
--avoidsource=AVOIDSOURCE
Modify the pointing to put the given source in a beam
null, but keep the given source coordinate as close as
possible to the beam centre.Only works if source name
or ra/dec/gall/galb used for target coordinates, not
az/el.
--azimuth=AZ_LIST, --az=AZ_LIST
Pointing direction in Az,El (dd:mm:ss or decimal
degrees).
--elevation=EL_LIST, --altitude=EL_LIST, --el=EL_LIST, --alt=EL_LIST
Pointing direction in Az,El (dd:mm:ss or decimal
degrees).
--delays=DELAYS_LIST, --hex=DELAYS_LIST
Pointing direction using raw beamformer delay settings
(a comma-separated list of 16 integers, each 0-32).
--calibration Does the observation contain a calibrator source?
--calibrator=CALIBRATORS, --calibrators=CALIBRATORS
Name(s) of the calibrator(s).
Coordinate adjusting options:
--useazel, --usealtaz
(default) Store Az/El values in the schedule entry
instead of RA/Dec values. Does not affect pointing
calculations.
--useradec Store RA/Dec values in the schedule entry instead of
Az/El values. Does not affect pointing calculations.
--nogrid Ignore the sweetspot grid and use beamformer delays
for the precise target coordinate. This will give a
degraded beam shape because only quantised integer
delays are possible.
--gridname=GRIDNAME, --usegrid=GRIDNAME
Use a different 'sweet spot' grid of az/el values
where the ideal geometric dipole delays are equal to
the quantised values allowed by the beamformer
hardware. Possible choices are ['EOR1', 'nogrid',
'sweet']. [default=sweet]
--maxgridsigma=MAXGRIDSIGMA
Only use grid positions with sigma <= this value.
Defaults to all grid positions.
--maxshift=MAXSHIFT, --move=MAXSHIFT
Split into sub-observations each time a moving source
has moved by > MAXSHIFT arcsec. Has no effect for a
fixed source. [default=60]
--dt=DT Sampling time in seconds to check observing
constraints, subobservations for moving sources, or
adaptive shift checks. [default=128]
--adaptiveshift, --adaptive
Split observing block into sub-observations as needed,
whenever the source is closer to a new sweet-spot.
Implies --grid
--maxlength=MAXLENGTH, --shifttime=MAXLENGTH
Split into sub-observations no longer than this length
in seconds, even if the sweet-spot hasn't changed, or
the source hasn't moved. [default=296]
--minaltitude=MINALTITUDE, --minelevation=MINALTITUDE
'Soft' altitude limit (issues warning if target below
this). [default=10]
--horizon=HORIZON 'Hard' altitude limit (does not create observation if
target below this). [default=0]
--minsundistance=MINSUNDISTANCE
Minimum distance from Sun in degrees. [default=-1]
--minjupiterdistance=MINJUPITERDISTANCE
Minimum distance from Jupiter in degrees. [default=-1]
--adjusttimes Should we adjust the start time to make sure the
source is above <minaltitude> and far enough away from
Sun/Jupiter? [default=False]
--nomode, --nomodechange
Obsolete, used for old correlator. Now does nothing.
--addcal=ADDCAL, --postcal=ADDCAL
If given, a 2-minute calibrator observation will be
appended, for each frequency setting specified in this
observation. If a name is given, that source will be
used as a calibrator, otherwise the best available
calibrator is chosen automatically.
--precal=PRECAL If given, a 2-minute calibrator observation will be
pre-pended, for each frequency setting specified in
this observation. If a name is given, that source will
be used as a calibrator, otherwise the best available
calibrator is chosen automatically.
--calexptime=CALEXPTIME
Observation time for calibrator observations.
[default=120]
--nostop, --novstop
Obsolete, used for old correlator. Now does nothing.
RF Stream settings:
Defines the receiver settings for the observation.
--rfstream=RFSTREAM_NUMBER
RF stream number [default=0], pass a non-zero value
for commensal observing.
--freq=FREQUENCIES_LIST, --frequencies=FREQUENCIES_LIST, --frequency=FREQUENCIES_LIST
Frequency, some of <channel>,
<channelstart>:<channelstop>:[<increment>],
<centerchannel>,<channelwidth>,[<increment>],
separated by ; (channels are 1.28 MHz coarse channel
numbers). [default=121,24]
--tile=TILESELECTION, --tiles=TILESELECTION, --tileset=TILESELECTION, --subarray=TILESELECTION
Tileset name, one of ['256T', 'all_east', 'all_ne',
'all_north', 'all_northeast', 'all_northwest',
'all_nw', 'all_on', 'all_on_x', 'all_on_y', 'all_se',
'all_south', 'all_southeast', 'all_southwest',
'all_sw', 'all_west', 'p1+hexes', 'p1+solar',
'p2_compact', 'p2_compact_OS', 'p2_extended',
'phase_one']
--atten=GAIN_CONTROL_VALUE, --attenuation=GAIN_CONTROL_VALUE, --gain_value=GAIN_CONTROL_VALUE, --gain_control_value=GAIN_CONTROL_VALUE
Hardware Attenuation in dB (used to be referred to as
'gain_control_value'). [default=1]
--unpowered=UNPOWERED
Name of the set of tiles to leave powered down for
this observation. [default=default]
--dipex=DIPEX Name of the set of dipoles to switch out for this
observation. [default=default]
General options:
-v, --verbose Each -v option produces more informational/debugging
output.
-q, --quiet Each -q option produces less
error/warning/informational output.
-n, --numeric Write a list of scheduled obsids on StdOut (all other
output goes to StdErr)
--force Force overwrite of an existing identical entry?
--nodb, --nodatabase
Do not actually write to the database.
--refresh Refresh the local cached copies of the database
tables.
--overwrite Overwrite any existing observations in the schedule.
--delete Delete any existing observations at the given time/s,
but don't schedule new ones
Use without a sourcename or position to see a few major sources that are visible at a given time. [default=now]: