Doc 4.19, ver. 1 | 2 August, 2016

A User’s Guide toALMA Scheduling Blocks(Cycle 4)

ALMA, an international astronomy facility, is a partnership of ESO (representing its member states), NSF (USA) andNINS (Japan), together with NRC (Canada), NSC and ASIAA (Taiwan), and KASI (Republic of Korea), in cooperation
with the Republic of Chile. The Joint ALMA Observatory is operated by ESO, AUI/NRAO and NAOJ.

For further information or to comment on this document, please contact your regional Helpdesk through the ALMA Science
Portal at www.almascience.org. Helpdesk tickets will be directed to the nearest ALMA Regional Center at ESO, NAOJ orNRAO.

VersionDateEditors

12 August 2016

G. Schieven

This document was produced by the National Research Council of Canada (Herzberg Astronomy & Astrophysics) with theNational Radio Astronomy Observatory, with contributions from staff of the European and East Asian ALMA Regional Centers(ARCs) and the Joint ALMA Observatory (JAO).

In publications, please refer to this document as:Schieven, G., ed., 2016, A User’s Guide to ALMA Scheduling Blocks, ALMA Doc. 4.19, ver. 12

Table of ContentsOT Version

3Introduction4Structure of SBs

5SB Naming Convention

5Groups

6

Targets

6

Resources

7

Field Sources

7

Instrument Setup

7Observing Parameters

7

Examining Your SBs

8

Science Source Positions and Radial Velocity

8

Instrument Setup

9

Integration Time

11

Array Configuration

12

Other Considerations

12

Appendix A - Acronyms used

13OT Version
The following is a guide for interpreting ALMA
Scheduling Blocks (SBs), using the ALMA
Observing Tool (OT). You will need todownload and install the latest version of theOT from the ALMA Science Portal atwww.almascience.org. To check that you’reusing a version of the OT set up for working
with SBs, click the “Help” menu, then click“About” and select the “Version” tab. You
should see PhaseII in the User version (seeFigure 1). If not, then download a more recent
version from the Science Portal. (The user
version is also shown on the startup screen.)This particular document has been updated foruse with the ALMA OT user version
Cycle4PhaseII(u1).

Figure 1: To determine which version of theOT you’re using, under the “Help” menu
select ”About…” and click the “Version” tab.
This document has been updated for use3

A Users’ Guide to ALMA Scheduling Blocks (SBs)Introduction
When preparing your ALMA proposal (aprocess often referred to as Phase 1) withProposal Tab
the ALMA Observing Tool (OT), you created
one or more Science Goals (SGs; Figure 2)
in which you specified the science targets
and properties, observing frequencies andcorrelator settings, required sensitivities, andother observing constraints. These can beviewed by clicking the “Proposal” tab (Figure2). After your project is approved, yourproposal enters Phase 2 (visible under the“Program” tab (Figure 3)), in which your SGs
are used to generate Scheduling Blocks(SBs) which contain all the instructions
needed by the telescope control software tocarry out your science and calibration
Figure 2: The “Proposal” tab shows theobservations. Before generating your SBs,Science Goals (SGs) exactly as they were
you will need to follow the procedures listed
generated by you when you prepared yourin the Phase 2 Quickstart Guide available on
proposal. The contents under this tab
the Science Portal at http://almascience.org/
cannot be edited or changed.
documents-and-tools/cycle4/phaseiiuserguide. Once your SBs have been
generated, this document will help you to interpret your SBs and how they relate to yourSGs and to the observations they will be used to carry out. Remember, however, that you
can always contact your Contact Scientist (CS) through the Helpdesk if you have anyquestions or concerns. (Note that VLBI and solar SBs are not included in this document.)

Program Tab

Folder Key

Figure 3: The “Program” tab (circled) contains the files generated at Phase 2, including theSBs. Clicking the folder key symbol exposes or hides the contents of the file. Right-clicking
the key symbol and selecting “Expand all” allows you to see all the files under that key.

4

Structure of SBs
Once you’ve generated your SBs, you’ll see a set of nested folders, similar to when you
created your SGs. To expand the folders, just click on the key symbols (circle with a line
segment; Figure 3) or expand them all using cntrl-z or right-click → expand all. The toplevel folder is the Project, the second level is the Science Plan, and the third level of thishierarchy contains the Science Goals. So far this is the same structure as you saw whengenerating your proposal. At Phase 2, a hierarchy of files called Observing Unit Sets
(OUSs; see Figure 4) is created from each SG, inside of which you’ll find your SBs. (For afull description of the OUS hierarchy, see the Technical Handbook, Chapter 8.)

Scheduling
Block Icon

Figure 4: Each SG
contains a hierarchy offiles called an Observing
Unit Set (OUS), which
include the SBs. Each SG
contains one or more SBs,
depending on whethermultiple arrays and/or
multiple tunings arerequired for the science
goal.

Depending on the angular resolution, largest angular structure (LAS), number of tunings, andsky distribution of science sources specified in the SG, at Phase 2 one or more SBs will begenerated for each SG, each in its own Member OUS. The SB can be identified by a squareclock icon (Figure 4).
SB Naming Convention
Each SB in your project has a unique name, with the structure SRCName_a_XX_AR, where‘SRCName’ is the first (up to) 8 characters of the representative science target, ‘XX’ is thereceiver band used (e.g. 03 for Band 3), ‘AR’ distinguishes the array (‘TM1’ or ‘TM2’ for the12m-Array, ‘7M’ for the 7m-Array, and ‘TP’ for the TP-Array), and ‘a’ has the value ‘a’, ‘b’, ‘c’,etc., to give the SB a unique name.
An example of an SB name might be ‘ru_lupi_b_03_TM1’, where ‘ru_lupi’ comes from the first(up to) 8 letters of the representative science source in the SB, ‘b’ means that there is anotherSB in the project with a similar name (i.e. ru_ lupi_a_03_TM1), ’03’ means the SB uses theBand 3 receivers, and ‘_TM1 means that this is a 12m Array observation. (If you had chosen5

an angular resolution andLAS combination that
required two 12m Arrayconfigurations, the SB for thesecond, more compact
configuration would havebeen labeled ‘_TM2’; see
Figure 4.)
Each SB is made up of three
sections: Groups, Targets,and Resources (Figure 5).
GroupsGroupsTargets

All observing targets that are to
be executed are included in aGroup within the SB. Each SB
can include multiple Groups.
The first, Group 1, generally
contains the initial calibration
Resources
observations (e.g. amplitude,bandpass, sideband ratio,etc.), and the targets within thisGroup are intended to be done
once per execution of the SB.
(Note, however, that forspectral scans, Group 1 isempty.) The second (orsubsequent) Group contains
the science targets plus
Figure 5: The basic structure of an SB consists of three
relevant calibrators (e.g.
elements: Groups; Targets; and Resources.
phase, atmosphere, pointing,etc.) which are repeated until
the science integration time is completed. If you click on a group, then the targets associatedwith that group are highlighted in yellow.
Targets
Targets define all the information needed for an observation, using Resources (see below).
There is one target for each science source or calibrator. Clicking on a target causes all of theresources associated with that target to be highlighted in yellow (Figure 5). All of the resource
parameters for the target are also shown at the same time in the Editor window (Figure 6).
One of the science targets is labeled with an ‘[R]’. This target is used as a representative
target for the SB when the Scheduler is looking for available SBs to observe.

6Editor
Window

Figure 6: All observing parameters for the SB are viewable in the Editor Window.

Resources
Resources define the parameters used for a particular type of observation. A resource may be
used by several targets. Clicking on the resource will highlight the targets making use of it inyellow. It also shows the parameters for that resource in the Editor window.
There are three types of resources (Figure 5):
Field Sources

Field Sources define the position (plus proper motion and parallax), offsets and radial
velocity of each source, including calibration sources. If multiple science sources weredefined in the SG, each will have its own field source. Calibration field sources areusually left as a query, to be defined at the time of the observation. Calibration
sources, because they tend to be variable, are monitored periodically by theobservatory. If there is no suitable calibrator in the catalogue, a “cone search” may becarried out prior to observing your SBs.
Instrument Setup

The instrument setup defines how the receiver is tuned and the correlator is set up.
Usually there are two setups: one for pointing, and one for the science observations, butin certain circumstances (e.g. multiple tunings for a spectral scan, multiple sources withdifferent redshifts, very narrow total bandwidth) there may be several science setups.
Observing Parameters

Observing parameters define the sub-scan duration (basic integration time) and thetotal integration time per execution of the SB for each target, as well as otherparameters.

7Examining Your SBs
The most common items that you might want to check in your SBs are the sciencesource positions and radial velocities, the instrument setups, the integration time, andthe array configuration in which the SB might be observed. We look at each item inturn.
Science Source Positions and Radial Velocity
Each science source has its own Field Source resource (Figure 7), where the source
position and radial velocity are defined. These values are copied directly from your SGs
when the SBs are generated, so in most cases will be unchanged. To see them,clicking on the Field Source (e.g. in Figure 7, the Field Source for RU Lupi) reveals theparameters in the Editor window to the right. Where a mosaic or offsets have been
specified, you may need to scroll down the Editor window to see them (Figure 8). Total
Power (_TP) science observations require a reference position, which your Contact
Scientist will request you to provide. That can be checked by scrolling down the Editorwindow.
On the top left corner of the Editor window (Figure 9), if you click on the Spatial tab you
can get a graphical view of the source position, offsets and mosaic positions. This view
works the same way as when you generated your SGs in Phase 1.

Figure 7: The Field Source resource, showing the position, radial velocity and velocity frame,
proper motion, and other properties.

8Figure 8: Offset positions (e.g. for a mosaic) are found by scrolling to the bottom of the Editor
window in the Field Source resource.
Spatial Tab

Figure 9: The Spatial tab
shows a graphicalpresentation of source
positions and offsets. A
background image must be
loaded from an online server
or using a local fits file.

Instrument Setup
Because of the power and flexibility of the ALMA correlator, the Instrument Setup resources aremuch more complex than the other resources, and interpreting them can be daunting. However,in most cases only a few numbers are relevant and can be checked quickly.
Click on the Science Instrument Setup resource (see Figure 5). The targets using this setup arehighlighted in yellow. Scrolling down the Editor window, near the bottom you’ll see (up to) fourtabs, one for each baseband (BB_1, BB_2, etc.; Figure 10). Click on each baseband tab in turn.
At the bottom of each baseband window is another set of 1-4 tabs, one for each spectral window(SW-1, SW-2, etc.; Figure 10). Click on each of these tabs in turn to check the center frequencyof the spectral window (rest and sky), the bandwidth, averaging factor, and spectral resolution(after smoothing and averaging).
If you have multiple SBs within an SG (Figure 3) due to multiple array configurations, then all of
the 12-m and 7-m Array SBs (_TM1, _TM2, _7m) and the science TP-Array SB (e.g.
ru_lupi_a_03_TP), should all have identical science instrument setups. The TP-Array calibration
SB (query_xxx_TP) may have a different instrument setup from the others.
9Baseband Tabs

Spectral Window Tabs

Center Frequency

BandwidthPolarization
Spectral Averaging Factor
Resolution aftersmoothing/averaging
Figure 10: Click on the Science Instrument Setup and scroll to the bottom of the Editor
window in order to check your correlator setup. Each baseband (BB) has its own tab, andeach spectral window (SW), if more than one within the baseband, has its own tab. Click oneach in turn to check the setup for each spectral window in each baseband.
Spectral Tab

Figure 11: A graphical view of thecorrelator setup using the Spectral
tab, showing the ranges for eachbaseband as well as the bandwidthand range of each spectral window.

10

Note that the Center Frequency of the spectral window may be slightly different from thedesired center frequency, by as much as 20 MHz. This is because the OT calculates the fullcorrelator tuning solution while generating the SBs, and the solution may differ slightly fromthe desired value. This may be a significant fraction of your spectral window width whenusing narrow windows.
On the top left corner of the Editor window, if you click on the Spectral tab you can get agraphical view of the correlator setup (Figure 11). This view is similar to the Spectral
view when you generated your SGs in Phase 1, except that now both the baseband
location and width as well as all spectral window widths are shown graphically.
Integration Time
Click on the Science Observing Parameter
resource (Figure 5). The target(s) using thissetup will be highlighted in yellow. In theEditor window (Figure 12) you can check theIntegration Time on Source, which is the total
integration time (per execution of the SB) for
each target using this resource (Figure 12).
(For targets with multiple offsets, e.g.
mosaics, the integration time per point will be
the integration time on source divided by thenumber of offsets.) The integration time on
source is limited so that the SB will becompleted in approximately 2 hours or lessincluding all calibration observations, so it willoften be shorter than the total integration timerequired. In this case, the SB may need to
be executed multiple times. Click on the SBicon (grey clock) and scroll down toExecution Count (Figure 13). The overall

Total Integration
Time On-Source perSB Execution

Figure 12: The Science Observing Parameter
resource shows, among other things, the total
integration time on source per execution of the SB.

Number of SB
Executions

Figure 13: Click on the SB name (yellow clock icon) and scroll down the Editor window to findthe Execution Count. The total time on source will be the Integration Time on Source (Figure12) multiplied by the Execution Count.

11

total integration time on source is then the execution count multiplied by the integration time on
source.
Note that if more than one array configuration is required for your SG (e.g. a second, morecompact 12m-Array configuration, and/or the ACA, etc.), then the integration time for the
more compact configuration(s) will be governed by the required integration time for the mostextended configuration (i.e. the SB with the ‘_TM1’ at the end of its name). For Cycle 4, theintegration time for the compact 12m-Array configurations (‘_TM2’) will have 30% of the total
integration time on source as the more extended configuration SB (‘_TM1’); the 7m-Array
and TP-Array SBs have a more complicated formula for determining the total integrationtime.
Array Configuration
Currently the ALMA observing
software uses the values of angularresolution (AR) and Largest Angular
Scale (LAS) stored in the Control andAngular Resolutionof Nominal
Performance section of the SG toConfiguration
determine which array configurations
are suitable for observing your SBs.
Click on the SB icon (square greyclock) and scroll down to the bottomof the editor window (Figure 14) tosee the nominal configuration which
the OT determines gives the closest
Nominalvalue to your requested AR. The OT
Configuration
also displays a “minimum” and“maximum” angular resolution, whichis effectively the angular resolution of
the nominal configuration (+/- 10%).
Figure 14: Click on the SB icon and scroll to theIf multiple 12m Array configurations
bottom of the editor window to see the Nominal
are required to achieve the LAS
Configuration, i.e. the configuration which
you’ve requested, then the _TM2 SBprovides the closest angular resolution to the PIrequested AR, in which the SB is most likely to be
will show the nominal configuration
observed. The Min./Max. Angular Resolution
and angular resolution (+/- 10%) ofdisplayed is the range of resolutions achievable
the more compact 12m Array
with the nominal array (depending on the chosenconfiguration. To confirm which arrayweighting during data reduction).
configurations are likely to be used
for your SBs, consult with yourContact Scientist through the ALMA Helpdesk.
Other Considerations
For other observing constraints, such as time constraints, observing cadences, TP-array
setups, etc., consult with your Contact Scientist through the ALMA Helpdesk.
12

Appendix A - Acronyms used
ACA - Compact array, including 7m Array and TP Array
ALMA - Atacama Large Millimeter/Submillimeter Array
AR - Angular Resolution
BB - baseband
CS - Contact Scientist
FDM - correlator spectral mode
JAO - Joint ALMA Observatory
LAS - Largest Angular Structure
OT - ALMA Observing Tool
PT - Project Tracker
SG - Science Goal
SB - Scheduling Blockspw - spectral window
TDM - correlator continuum mode
TP Array - total power array, part of ACA

13!

The Atacama Large Millimeter/submillimeter Array (ALMA), aninternational astronomy facility, is a partnership of the European
Organization for Astronomical Research in the Southern Hemisphere(ESO), the U.S. National Science Foundation (NSF) and the National
Institutes of Natural Sciences (NINS) of Japan in cooperation with theRepublic of Chile. ALMA is funded by ESO on behalf of its Member
States, by NSF in cooperation with the National Research Council ofCanada (NRC) and the National Science Council of Taiwan (NSC) andby NINS in cooperation with the Academia Sinica (AS) in Taiwan andthe Korea Astronomy and Space Science Institute (KASI).
ALMA construction and operations are led by ESO on behalf of its
Member States; by the National Radio Astronomy Observatory(NRAO), managed by Associated Universities, Inc. (AUI), on behalf ofNorth America; and by the National Astronomical Observatory ofJapan (NAOJ) on behalf of East Asia. The Joint ALMA Observatory(JAO) provides the unified leadership and management of theconstruction, commissioning and operation of ALMA.

14