Doc 4.5, Ver. 1.0| Mar, 2016 ALMA Observing Tool User Manual Andy Biggs, Rein H. Warmels ALMA,aninternationalastronomyfacility,isapartnershipofESO(representingitsmemberstates),NSF(USA) andNINS(Japan),togetherwithNRC(Canada),NSCandASIAA(Taiwan),andKASI(RepublicofKorea),in cooperationwiththeRepublicofChile. TheJointALMAObservatoryisoperatedbyESO,AUI/NRAOandNAOJ. Forfurtherinformationortocommentonthisdocument,pleasecontactyourregionalHelpdeskthroughtheALMAUser Portal at www.almascience.org. Helpdesk tickets will be directed to the appropriate ALMA Regional Centre at ESO, NAOJorNRAO. Version Date Editors 0.5,Ver. 1.0 March2011 ReinWarmels 0.5,Ver. 1.1 August2011 ReinWarmels 1.5,Ver. 1.0 May2012 ReinWarmels 1.5,Ver. 1.1 October2012 AndyBiggs 1.5,Ver. 1.2 February2013 AndyBiggs 1.5,Ver. 1.3 February2013 AndyBiggs 2.5,Ver. 1.0 October2013 AndyBiggs 3.5,Ver. 1.0 March2015 AndyBiggs 4.5,Ver. 1.0 March2016 AndyBiggs TheALMAOTTeam,andthemanyTesters. Inpublications,pleaserefertothisdocumentas: OTUserManual4.5,Version1.0 Contents 1 Introduction 5 1.1 How to Use this Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.2 User Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.3 Release Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.4 Credits and Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2 Install and Run the Observing Tool 7 2.1 Hardware and Software Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.1.1 Java Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.1.2 Supported Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.1.3 Disk Space Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.2 Using the OT with Java Web Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.2.1 Verifying Java Web Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.2.2 Starting the OT with Web Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.2.3 Running the OT offline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.3 Tarball Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.3.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.3.2 Starting the OT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 2.4 Connecting Through a Proxy Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3 Basic Concepts 13 3.1 Phase-1 Proposals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.2 Phase-2 Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.3 Science Goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.4 Observing Unit Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 3.5 Scheduling Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 3.6 Project Submission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.7 Project Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.8 AOT files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 3.9 Project Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 4 Overview of the Observing Tool 17 4.1 Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 4.2 The OT Main Graphical Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 4.2.1 GUI Parameter Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 4.2.2 GUI Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 4.2.3 Menu and Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 4.2.4 The OT Panes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 4.2.4.1 The Project Structure Pane. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 4.2.4.2 The Editors Pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 4.2.4.3 The Feedback Pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 4.2.4.4 The Overview Pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 4.3 OT Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 1 5 Phase 1 – Observing Proposal 23 5.1 Open a Phase-1 Proposal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 5.2 The Proposal Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 5.2.1 Adding Investigators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 5.2.2 Scientific Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 5.3 Adding Phase-1 Science Goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 5.3.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 5.3.2 Field Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 5.3.2.1 Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 5.3.2.2 Source clustering/Psuedo-Science Goals . . . . . . . . . . . . . . . . . . . . . . . 26 5.3.2.3 Resolving source information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 5.3.2.4 Expected Source Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 5.3.2.5 Field definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 5.3.2.6 Import/Export of Source Information . . . . . . . . . . . . . . . . . . . . . . . . 28 5.3.3 Spectral Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 5.3.3.1 Spectral Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 5.3.3.2 Polarization Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 5.3.3.3 Spectral Line – one spectral window per baseband . . . . . . . . . . . . . . . . . 29 5.3.3.4 Spectral Line – more than one spectral window per baseband . . . . . . . . . . . 29 5.3.3.5 Representative Frequency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 5.3.3.6 Single Continuum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 5.3.3.7 Spectral Scan. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 5.3.3.8 Multiple velocities and tuning solutions . . . . . . . . . . . . . . . . . . . . . . . 31 5.3.4 Calibration Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 5.3.5 Control and Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 5.3.5.1 Imaging considerations: arrays and configurations . . . . . . . . . . . . . . . . . 33 5.3.5.2 Sensitivity considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 5.3.5.3 Time Estimation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 5.3.5.4 Overriding the OT’s time estimate . . . . . . . . . . . . . . . . . . . . . . . . . . 35 5.3.5.5 Time specification - Solar and VLBI . . . . . . . . . . . . . . . . . . . . . . . . . 35 5.3.5.6 Time-constrained observing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 5.3.6 Technical Justification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 5.4 Summary Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 5.5 Proposal Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 5.6 Proposal Submission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 6 Phase 2 – Observing Program 39 6.1 Generation from Science Goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 6.1.1 Phase-2 Science Goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 6.1.2 Scheduling Block Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 6.1.3 Manual creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 6.2 Observing Program Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 6.2.1 Observing Unit Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 6.2.2 Scheduling Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 6.2.3 Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 6.2.4 Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 6.2.4.1 Field Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 6.2.4.2 Instrument Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 6.2.4.3 Observing Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 6.2.5 Observing Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 6.3 Submit the Observing Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 2 7 Tools 49 7.1 The ALMA Template Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 7.2 Sensitivity Calculator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 7.3 Spectral Line Selection Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 7.4 Archive Search Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 7.5 Calibrator Selection Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 7.6 LO Configuration Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 8 The Visual Spatial Editor 55 8.1 Overview of the Graphical Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 8.2 Creating a Field Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 8.2.1 Single Pointings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 8.2.2 Rectangular Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 8.2.2.1 Science Goal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 8.2.2.2 Scheduling Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 8.2.3 Offset Versus Absolute Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 9 The Visual Spectral Editor 59 9.1 Overview of the Graphical Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 9.2 Viewing a Spectral Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 9.2.1 Science Goal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 9.2.2 Scheduling Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 A Create an External Ephemeris 63 A.1 NASA resources for HORIZONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 A.2 Instructions and Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 A.3 Example Ephemeris . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 B Acronym List 67 3 This page was intentionally left almost blank 4 Chapter 1 Introduction The OT User Manual describes the ALMA Observing Tool (OT) that is used to prepare observing proposals (Phase 1) and to schedule approved observations (Phase 2) for the Atacama Large Millimeter/submillimeter Array (ALMA). The OT is a Java-based application consisting of a set of user interfaces that are needed to prepare an ALMA observing project. This consists of a valid observing proposal and/or an observing program containing one or more Scheduling Blocks that are executed at the telescope. 1.1 How to Use this Manual Firstly, it is important to explain what this manual is not. • It is not a step-by-step guide to creating an ALMA proposal and/or observing program. Especially for inexperiencedusers,suchastep-by-stepguidetoproposalcreationisavailableintheformoftheOTQuick Start Guide, which can be obtained either through the OT’s internal help system or through the ALMA SciencePortal. ObservingprogramsarenotintendedtobecreatedbynormalusersandthereforeaPhase-2 counterpart does not exist. • This manual is also not designed to describe everything that can be possibly be done with the OT, and in particular does not give an explanation of what each and every entry field in the OT does. If this is desired, then the OT Reference Manual should be consulted. • Detailed technical information about ALMA is also not provided although, particularly with regard to the tuning and correlator setups, the basics are covered. The ALMA Technical Handbook is highly recom- mended for those users who want to know, well, everything. Instead, this manual attempts to give an overview of what is possible with the OT, without going in to the kinds of detail covered in the resources mentioned above. Therefore, Phase-1 proposals are described in terms of their main components, their purpose and what kind of information should be entered. Where detail is given, it generally covers aspects of the OT that are not obvious. A list of acronyms (Appendix B) may prove useful. UserswhoarecompletelyunfamiliarwiththeOTarerecommendedtoreadthefollowingchapters: Chapter2 provides information about how to install, configure and run the Observing Tool, Chapter 3 describes the main components of an observing proposal and program, and Chapter 4 provides a general overview of the OT. In order to create a Phase-1 proposal, all the essential information is covered in Chapter 5 – this describes the process in some detail and should be read by all users. Complementary to this is Chapter 7 which describes various OT tools and Chapters 8 and 9 that give detailed information on how to use the visual spatial and spectral editors. Phase-2 programs are covered in Chapter 6, although the chapters that cover the tools and visual editors remain relevant. As normal users do not create Phase-2 programs themselves, Chapter 6 is more intended for expert users and observatory staff. The same applies to the Appendices that also cover special topics. 5 1.2 User Support Ineachofthethreepartnerregions,anALMARegionalCentre(ARC)hasbeenestablished. EachARCprovides scientific user support in the core areas of proposal preparation (Phase 1), observation program preparation (Phase 2) and data analysis to users in their respective communities. The ARCs will also host copies of the ALMA Archive and will deliver data packages to users. Hence, the ARCs are the ALMA interfaces to the user. More detailed information about the ARCs and how the interaction with the user communities is organised can be obtained from their Web sites. The following three URLs point to the European, North American, and East Asian ARC sites: Europe: http://www.eso.org/sci/facilities/alma North America: https://science.nrao.edu/facilities/alma East Asia: http://alma.mtk.nao.ac.jp/e/ Before and after the observations you will have regular interaction with your ARC. The degree of interaction will vary and depend on your experience and the complexity of the project undertaken. For simple projects, experienced users may only need to submit their Phase-1 and Phase-2 programs without any need for further supportandtheywillreceivetheirdatapackagefromtheARCs. Inexperiencedusersandmorecomplexprograms may require active ARC support during all phases of the observing program. IntheeventyouencounteraproblemorneedsupportwhenusingtheALMAObservingToolyoucancontact the ALMA User Support Service at your ALMA Regional Centre (ARC) or use the ALMA Helpdesk. All of these can be reached via the ALMA Science Portal: http://www.almascience.org 1.3 Release Information This version of the manual is intended to be used with the OT that will be used to create Phase-1 proposals for ALMA Cycle 4, either a one submitted at the standard deadline, or a Director’s Discretionary Time (DDT) proposal that can usually be submitted once observing has begun. A completely separate version of the OT is currently available for the preparation of Phase-2 programs and DDT proposals for Cycle 3. 1.4 Credits and Acknowledgements The ALMA OT is a software product of the ALMA Observation Preparation Software Team and is developed on the basis of the ALMA Science Software Requirements (SSR) and the ALMA High Level Analysis (HLA) documents, produced by the respective groups. The OT software group acknowledges the valuable inputs of these groups during the development phases of the OT. Testers from the external community are also thanked for their valiant efforts over the years. 6 Chapter 2 Install and Run the Observing Tool The ALMA OT is written in Java and can be installed in two different ways, using Java Web Start and with a traditionaltarballdistribution. WestronglyrecommendtheWebStartasitwillensurethatyouarerunningthe latest available version of the OT by automatically downloading a new version if this is available. The tarball method involves more steps on the part of the user and any updates will need to be installed manually. In this chapter, both installation procedures will be discussed. If problems are encountered during installation and/or operation of the OT, users are recommended to examine the Science Portal, especially the OT Troubleshooting and Known Issues pages, for solutions. The Helpdesk1 may also contain useful information via its Knowledgebase system. If a solution to a problem cannot be found, a user should then file a Helpdesk ticket. 2.1 Hardware and Software Prerequisites 2.1.1 Java Software In order to use the OT, it should only be necessary that the computer in question has Java installed. Most computers have Java pre-installed, but if this is not the case, the latest version of Java (also known as the Java Runtime Environment or JRE) should be downloaded from http://java.com/. We strongly recommend that the Java version be regularly updated to the latest official Oracle release as the OT cannot otherwise be guaranteed to work. OpenJDK versions (Linux distributions often come with these as default) may appear to function correctly, but are known to cause some problems. If a deprecated version of Java is being used, the OT will issue a warning. The currently installed version can be checked by typing java -version on the command line, the output of which should look something like this: java version "1.8.0_65" Java(TM) SE Runtime Environment (build 1.8.0_65-b17) Java HotSpot(TM) 64-Bit Server VM (build 25.65-b01, mixed mode) The number that follows the underscore refers to which update of the Java version has been installed. Updates appearregularlyandshouldalwaysbeinstalled. WhenreportingaproblemwiththeOT,thefullversionnumber including the update should be reported. 1https://help.almascience.org/ 7 2.1.2 Supported Platforms The OT should run on any machine that has an appropriate version of Java installed. This is because the JRE includes a Java Virtual Machine (JVM) which actually executes the platform-dependent OT code. Regular testingoftheOThasfoundthatitworksusingallcommonLinuxdistributions,MacOSXandWindows. When reporting bugs, the platform on which the OT is installed should be included. 2.1.3 Disk Space Required To install the ALMA Observing Tool via Java Web Start or by unpacking the tarball requires approximately 100 MBytes – including Java makes the distribution somewhat larger. If Web Start is used, this space must be availableinthelocationwhereyourJavaWebStartisconfiguredtoinstalldownloadedapplications. Thedefault for this will be a subdirectory of your home space (Unix/MacOS/Linux) or in the profile area (Windows). In case of a tarball installation the disk space must be available in the location where the OT will be installed. 2.2 Using the OT with Java Web Start Using Java Web Start is the recommended way of running the OT. This is because the first installation of the OT is usually easier and updates to the OT are automatically detected and installed. 2.2.1 Verifying Java Web Start A Java installation should include Web Start by default and so does not need to be installed separately. The very first download of the Web Start version must take place through a browser and, although this will usually be correctly configured to launch Web Start when the OT is selected in the ALMA Science Portal, this may not always be the case. Linux users will often find that IcedTea is the default version of Java and this ideally should be changed. On Firefox, this is done via the Applications tab of the Preferences menu (Figure 2.1). Figure2.1: AnexampleoftheApplicationsmenuinFirefoxthatcanbeusedtochangetheversionofWebStart used by the browser. This is for a Linux version of Firefox. 8