LINC-NIRVANA – Twice As Nice – Installation and User’s Manual

Doc. No. LN-MPIA-MAN-ICS-010 Short Title TAN Installation and User’s Manual Issue 4.044 Date February 13, 2020

Prepared . .Richard ...... J. . . . Mathar ...... (MPIA) ...... February ...... 13, . . . . 2020 ...... Name Date Signature

Approved ...... N. N. Name Date Signature

Released . .N. . . . N...... Name Date Signature ii LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044

Change Record

Issue Date Sect. Reason/Initiation/Documents/Remarks 0.131 2016-11-08 all created 4.044 February 13, 2020 all SVN version 16205M LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 iii

Contents

1 OVERVIEW 1 1.1 Acronyms...... 1 1.2 References...... 3

2 INSTALLATION5 2.1 Environment...... 5 2.2 SVN...... 5 2.3 Compiler...... 6 2.3.1 openSUSE...... 6 2.3.2 CentOS...... 6 2.4 Atlas...... 7 2.4.1 CentOS...... 7 2.4.2 openSUSE...... 7 2.4.3 gfortran...... 8 2.5 Ice...... 8 2.6 Compilation...... 9 2.6.1 Patches...... 10 2.6.2 Installation...... 10

3 CONFIGURATION 12 3.1 IIF FITS Header Keywords...... 12 3.2 ICS FITS Header Keywords...... 12 3.3 Port numbers...... 13

4 Linc-Nirvana 14 4.1 Angles...... 14 4.1.1 Standard Spherical Astronomy...... 14 4.1.2 Parallactic Angle...... 16 4.1.3 LBTO Coordinate System...... 19 4.1.4 Nominal Angles...... 21 4.1.5 Derotator Angles...... 22 4.2 Orientation of patrol camera images...... 23 4.2.1 Calibration...... 23 4.2.2 Guiding Offsets...... 28 4.3 Infrared Detector Images...... 29 4.3.1 Orientation...... 29 4.3.2 Derotation...... 29 4.3.3 WCS...... 30 4.4 User Interface...... 31 4.4.1 plotSkyTrack.py...... 31 4.4.2 Star catalogues...... 31 4.5 Notes on the IIF...... 40 4.5.1 Wait For End-of-slewing...... 41 4.5.2 Offset of the Rotator Polynomials...... 41 4.5.3 Direct Access via Python...... 42 4.6 Commands...... 43 iv LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044

5 IR OPTICS 55 5.1 Atmospheric Dispersion...... 55

6 TROUBLE SHOOTING 56 6.1 FAQ...... 56

7 EXTERNAL SOFTWARE 57 7.1 LBTO SW...... 57 7.1.1 Telescope Simulator...... 58 7.1.2 Telescope ICE Interface...... 63 7.2 Python...... 65 7.3 Xephem...... 65 7.3.1 Installation...... 65 7.3.2 LBTO parameters...... 66 7.3.3 Where is the LBT?...... 67 7.4 doxygen...... 67

List of Figures

1 Parallactic angle of δ and h ...... 17 2 Parallactic angle of δ and h for visible objects...... 18 3 Image orientation at instrument focus...... 20 4 Effect of elevation on SX PCam image...... 24 5 Effect of elevation on DX PCam image...... 25 6 plotSkyTrack GUI...... 32 7 Coverage of SE in DX GWS...... 33 8 Coverage of SE in SX GWS...... 34 9 Coverage of SE in DX HWS...... 35 10 Coverage of SE in SX HWS...... 36 11 Image oreintation in GWS focus...... 37 12 Bearing mismatch in GWS focus...... 38 13 Air Dispersion...... 55 14 TCS simulator...... 60 15 KFP coordinate system...... 64 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 1

1 OVERVIEW

A recent version of this document is in my home page and a slightly older in the LN documentation archive. The API is in this URL.

1.1 Acronyms

AO Adaptive Optics

API Application Programmer Interface

BASDA Basda Applications Services Devices Architecture (of Twice-As-Nice)

CCD Charge Coupled Device ccw counter clock wise cw clock wise

DEC declination coordinate of the ICRF

DHCP Dynamic Host Configuration Protocol

DNS Domain Name Service

DX Right (dexter) arm of the LBT optics

EDT Engineering Design Team http://www.edt.com/

ESO European Southern Observatory http://www.eso.org

FFTS Fringe and Flexure Tracking System of Linc-Nirvana

FITS Flexible Image Transport System http://fits.gsfc.nasa.gov

GEIRS Generic Infrared Software

GUI Graphical User Interface

GWS Ground-layer Wavefront Sensor (of Linc-Nirvana)

HWS High-layer Wavefront Sensor (of Linc-Nirvana)

ICE Internet Communications Engine https://en.wikipedia.org/wiki/Internet_Communications_Engine https://doc.zeroc.com/

IIF Instrument Interface of the LBT http://wiki.lbto.org/twiki/bin/view/SoftwareProducts/TCSsoftware

IP Internet Protocol

IR Infrared

LBT Large Binocular Telescope http://www.lbto.org/ 2 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044

LBTO Large Binocular Telescope Observatory http://www.lbto.org/ LINC LBT Interferometric Camera http://www.mpia-hd.mpg.de/LINC/ LN LINC-NIRVANA LUCI LBT NIR spectroscopic Utility with Camera and Integral-Field Unit for Extragalactic Research http://www.mpe.mpg.de/ir/lucifer MCS Mount Control System http://wiki.lbto.org/bin/view/Software/MCSPUBuildAndInstall MJD Modified Julian Date MPIA Max-Planck Institut f¨urAstronomie, Heidelberg http://www.mpia.de MPIfR Max-Planck Institut f¨urRadioastronomie, Bonn http://www.mpifr-bonn.mpg.de NCP North Celestial Pole NIRVANA Near-Infrared / Visible Adaptive Interferometer for Astronomy PC Pre-Commissioning Run (of Linc-Nirvana) PCI Peripheral Component Interconnect PCS Pointing Control System (of LBT) PLX PLX Technology, http://www.broadcom.com/products/pcie-switches-bridges/software-dev-kit

RA Right Ascension rpm RPM package manager rpm.org SE Star Enlarger (of Linc-Nirvana) SOFA Standards of Fundamental Astronomy http://www.iausofa.org SVN Subversion http://subversion.apache.org SX Left (sinister) arm of the LBT optics TAD transverse atmospheric dispersion TAI International atomic time https://en.wikipedia.org/wiki/International_Atomic_Time TAN TwiceAsNice https://svn.mpia.de/trac/gulli/TwiceAsNice TCS Telescope Control System UTC Universal Time Coordinated VM Virtual Machine WCS World Coordinate System http://atnf.csiro.au/people/mcalabre/WCS/ XML Extensible Markup language https://en.wikipedia.org/wiki/XML LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 3

1.2 References

References

[1] R. J. Mathar, LINC-NIRVANA - Generic Infrared Software, Graphical User Manual, LN- MPIA-MAN-ICS-007 (2 Oct. 2018). URL https://www.mpia.de/~mathar/public/LN-MPIA-MAN-ICS-007.pdf [2] F. Kittmann, LINC-NIRVANA - EDTpdv Camera User Manual, LN-MPIA-MAN-ICS-004 (14 Mar. 2007).

[3] I. F. W. Group, Definition of the flexible image transport system (FITS), version 4.0 (2016). URL https://fits.gsfc.nasa.gov/fits_standard.html

[4] K. R. Lang, Astrophysical Formulae, 3rd Edition, Vol. II of Astronomy and Astrophysics Library, Springer Verlag, Berlin, Heidelberg, 1998, E: In the second line of (5.45), sin A should read cos A.

[5] R. J. Mathar, Spherical trigonometry of the projected baseline angle, Serb. Astr. J. 177 (2008) 115–124, E: the sine in the equation on the second line of p 117 should be squared. doi: 10.2298/SAJ0877115M.

[6] W. M. Smart, Text-book on Spherical Astronomy, 4th Edition, Cambridge University Press, Cambridge, 1949.

[7] S. E. Urban, P. K. Seidelmann (Eds.), Explanatory supplement ot the Astronomical Almanach, 3rd Edition, Univ. Science Books, 2012.

[8] H. Karttunen, P. Kr¨oger,H. Oja, M. Poutanen, K. J. Donner (Eds.), Fundamental Astronomy, Springer, Berlin, Heidelberg, 1987.

[9] L. G. Taff (Ed.), Computational Spherical Astronomy, Wiley, New York, Rochester, 1981.

[10] J. Oprea, Geometry and the foucault pendulum, Am. Math. Monthly 102 (6) (1995) 515–522. doi:10.230/2974765.

[11] S. Newcomb (Ed.), A compendium of spherical astronomy, Dover Publications, 1960.

[12] S. Egner, T. Bertram, LINC-NIRVANA - Field Rotation, lN-MPIA-TN-SYS-002 (06 Apr. 2009). URL https://svn.mpia.de/trac/gulli/ln/archive/Archive/LN%20Documentation/ Technical%20Notes%20(TN)/Systems%20Engineering%20(SYS)/LN-MPIA-TN-SYS-002.pdf

[13] D. Miller, LBT Project, LBTO coordinate system description, 002s105 (22 Jan. 2010). URL http://abell.as.arizona.edu/~hill/xlbt/lbts/002s105b.pdf [14] D. Lorenzetti, F. D’Alessio, G. L. Causi, F. Pedichini, R. Soci, R. Speziali, F. Vitali, LINC- NIRVANA - Patrol Camera - Optomechanics and CCD System, lN-INAFR-FDR-AO-001 (29 Apr. 2005).

[15] T. Herbst, LINC-NIRVANA Pathfinder Telescope Installation, LN-MPIA-TN-AIT-068 (5 Oct. 2017). 4 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044

[16] P. Bizenberger, R.-R. Rohloff, H. Baumeister, LINC-NIRVANA - Warm Dichroics ICS, lN- MPIA-ICD-OPT-001 (20 Feb. 2012).

[17] M. Bergomi, B. Brunelli, V. Viotto, LINC-NIRVANA - K-mirror design report, lN-INAFP- DES-AO-002 (21 Mar. 2011).

[18] T. Herbst, LINC-NIRVANA - Angles and Coordinates, lN-MPIA-TN-SYS-039 (16 Mar. 2017). URL https://svn.mpia.de/trac/gulli/ln/archive/Archive/LN%20Documentation/ Technical%20Notes%20(TN)/Systems%20Engineering%20(SYS)/LN-MPIA-TN-SYS-039.pdf

[19] C. Biddick, LBT Project, Ice Instrument Interface Control Document, 481s013. E: the first value for OffsetPointing in RADEC coordinates is not seconds of time but radians. It actually is the change ∆(α cos δ) (9 Jul. 2016). URL http://abell.as.arizona.edu/~hill/xlbt/cgi/ican.cgi?481 [20] P. Bizenberger, LINC-NIRVANA - Warm Optics - Design and Analysis Report, lN-MPIA- DES-OPT-001 (09 May 2014). URL https://svn.mpia.de/trac/gulli/ln/archive/Archive/LN%20Documentation/ Design%20Report%20(DES)/Optics%20(OPT)/LN-MPIA-DES-OPT-001.pdf

[21] T. Bertram, LINC-NIRVANA Pathfinder Telescope Installation, LN-MPIA-TN-AIT-049 (19 Apr. 2013).

[22] E. Diolaiti, L. Mohr, F. D. Bonis, J. Farinato, R. Soci, LINC-NIRVANA - Mid High layer wavefront sensor - Design Report, lN-INAFB-DES-AO-001 (23 Mar. 2011). URL https://svn.mpia.de/trac/gulli/ln/archive/Archive/LN%20Documentation/ Design%20Report%20(DES)/Adaptive%20Optics%20(AO)/LN-INAFB-DES-AO-001.pdf

[23] R. Hofferbert, LINC-NIRVANA to LBT Interface Control Document, lN-MPIA-ICD-GEN-001 (19 Jun. 2015). URL https://svn.mpia.de/trac/gulli/ln/archive/Archive/LN%20Documentation/ Interface%20Control%20Documents%20(ICD)/LN-MPIA-ICD-GEN-001.pdf

[24] T. Sargent, M. D. Pena, J. Kraus, D. Cox, LBT Project, Preliminary instrument rotator control software specification, 678s001e (02 Jan. 2007). URL http://abell.as.arizona.edu/~hill/xlbt/lbts/678s001e.doc [25] R. J. Mathar, Atmospheric refraction path integrals of ground-based interferometry, Baltic Astronomy 14 (2) (2005) 277–298.

[26] S. Egner, LINC-NIRVANA - Atmospheric Differential Refraction, lN-MPIA-TN-SYS-001 (27 Feb. 2007). URL https://svn.mpia.de/trac/gulli/ln/archive/Archive/LN%20Documentation/ Technical%20Notes%20(TN)/Systems%20Engineering%20(SYS)/LN-MPIA-TN-SYS-001.pdf

[27] R. J. Mathar, Calculated refractivity of water vapor and moist air in the atmospheric window at 10 micron, Appl. Opt. 43 (4) (2004) 928–932. doi:10.1364/AO.43.000928.

[28] R. M. Wagner, M. L. Edwards, O. Kuhn, D. Thompson, C. Veillet, An overview and the current status of instrumentation at the large binocular telescope, in: S. K. Ramsay, I. S. McLean, H. Takami (Eds.), Ground-based and Airborne Instrumentation for Astronomy V, Vol. 9147 of Proc. SPIE, Int. Soc. Optical Engineering, 2014, p. 914705. doi:10.1117/12.2056787. LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 5

2 INSTALLATION

2.1 Environment

The environment variables needed for the LN installation are build around the INSROOT variable which are typically set in $HOME/.bash login with a template like if [[ $BASH_SUBSHELL -eq 0 ]] ; then export INSROOT=$HOME/insroot # or similar export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${INSROOT}/lib export PATH=${HOME}/bin:${INSROOT}/bin:$PATH export PYTHONPATH=${PYTHONPATH}:${INSROOT}/lib/python/site-packages export MANPATH=$INSROOT/man:$MANPATH export INFOPATH=${INFOPATH}:${INSROOT}/share/info export USERNAME="R._J._Mathar" export [email protected] export DOMAIN=mpia-hd.mpg.de # or mountain.lbto.org export QT_PLUGIN_PATH=$INSROOT/lib/plugins:$QT_PLUGIN_PATH fi (It is a bad idea to use spaces in USERNAME because the same environment variable will for example be used inside firefox for automatic directory creation, with the usual detremental effects on Unix/Linux systems.)

2.2 SVN

The SVN sources are obtained for example with mkdir -p $HOME/lnsw cd $HOME/lnsw svn checkout https://svn.mpia.de/gulli/TwiceAsNice/branch/unstable/TwiceAsNice TwiceAsNice svn checkout https://svn.mpia.de/gulli/TwiceAsNice/branch/unstable/ln ln svn checkout https://svn.mpia.de/gulli/ln/config config This creates directories TwiceAsNice, config and ln in the current working directory. It is not recommended to work on TwiceAsNice/trunk which is usually obsolete. The sources (exported but not checked out) need roughly 490 MB of disk space. The sources (directories TwiceAsNice, ln and config) checked out need roughly 760 MB of disk space. This volume will inflate to more than 3.1 GB during compilation, which need to be available on that partition. If checked out (which means, including the .svn) this will grow to 4.8 GB. For generic information look into https://svn.mpia.de/trac/gulli/TwiceAsNice. Some software bundles of the Linux repositories are needed: cd TwiceAsNice sudo ./suse-dep.install # for openSUSE, ln-x1, ln-x2, ln-x3 sudo ./centos-dep.install # for CentOS, lsys, lsys2, laos, laos2, lircs # zypper in python3-scipy # not needed yet Although this will install under openSUSE 15.0 many of the boost libraries, they are not installe 6 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 such that they will be found by make while compiling TaN. One usually needs to add links like cd /usr/lib64 ln -s libboost_filesystem.so.1.66.0 libboost_filesystem.so ln -s libboost_date_time.so.1.66.0 libboost_date_time.so ln -s libboost_system.so.1.66.0 libboost_system.so ln -s libboost_regex.so.1.66.0 libboost_regex.so If openSUSE complains that qwt4-devel is not available, insert qwt-devel in suse-dep.install at its place. Note that the installation does not find any cfitsio library which may be present in the GEIRS directories. Newer versions of TAN need the Python astropy package. If the compiler says it is missing run (as root) pip install --target=$INSROOT astropy astroplan Unfortunately that may install the library in /usr/lib64/python3.4/site-packages if python3 is your default, where the current search options in the TAN autotools are only recognizing python 2.7. So you may instead need the more explicit python --version zypper install python-pip pip2.7 install --target=$INSROOT astropy astroplan if only python3-pip is installed.

2.3 Compiler

2.3.1 openSUSE

If not the default compiler (likely gcc 4.8 at the moment) is desired but the newer gcc-6, upgrade the three variables before continuing. Under openSUSE this means: zypper install gcc6-c++ gcc6 cpp6 Finally add for all users in .bashrc export CPP=cpp-6 export CXX=g++-6 export CC=gcc-6 Starting with openSUSE Leap 15.0, gcc 7 is already the default and no such step is needed.

2.3.2 CentOS

Under CenOS there are no such repositories. There may be ways to http://www2.mpia-hd.mpg. de/~mathar/progs/recompileGCC.pdfcompile it yourself. The standard way of upgrading the compiler is yum install centos-release-scl devtoolset-7-gcc-c++ scl enable devtoolset-7 bash LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 7 g++ -dM -E -x c++ /dev/null | grep -F __cplusplus

2.4 Atlas

2.4.1 CentOS

For CentOS, the linear algebra package ATLAS is available as a standard package, but for open- SUSE 42.3 we need to compile it if we want to compile the ln/3rdparty directory. This is actually only needed to compile sextractor, but not if one can obtain the executable sex(1) from somewhere else.

2.4.2 openSUSE

The rpm source package is obtained from https://software.opensuse.org/package/libatlas3, then moved into /usr/src, and compiled with rpmbuild --recompile libatlas3-3.10.3-2.1.src.rpm cd /usr/src/packages CFLAGS=-shared rpmbuild -ba SPECS/libatlas3.spec zypper install RPMS/x86_84/libatlas*devel*.rpm # answer 2 to break dependencies ! If the rpmbuild step stops with a message that you have throttling enabled—which seems to happen on all Intel CPU’s— try cpupower frequency-set -g performance and rpmbuild again. If this did not help,1 you need to compile everything on a lower level: cd /usr/src/packages/BUILD/ATLAS mkdir tmp cd tmp ../configure --cripple-atlas-performance --shared --prefix=/usr --libdir=/usr/lib64/atlas - b 64 make make install cd /usr/src/packages/SPECS rpmbuild --rmsource libatlas3.spec cd /usr/lib64/atlas ln -s libsatlas.so libsatlas.so.3 ln -s libtatlas.so libtatlas.so.3 Finally set the CPU governor back to normal cpupower frequency-set -g conservative Installation of the new library may have detrimental effects on the numpy python package, which is linked to some of the linear algebra functions. So one should check that

1I tried to load the lenovo computers with a dummy program of lnsw/ln/3rdparty/src/sextractor/demandCPU, compiled with g++ -O0 that used the system fully on all processors which had no influence on the internal ATLAS guesser. . . 8 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 python >>> import numpy >>> import scipy.signal still works. If this fails due to missing functions, pip uninstall numpy pip install --target=$INSROOT numpy pip uninstall scipy pip install --target=$INSROOT scipy may bring them back.

2.4.3 gfortran

On some systems libgfortran is not properly installed because a package manager forgot symbolic links2: cd /usr/lib64 if [ -a libgfortran.so.3 ] ; then if [ ! -a libgfortran.so ] ; then ln -s libgfortran.so.3 libgfortran.so fi fi

2.5 Ice

There are two installation options. To start from the rpm packages in https://zeroc.com/download.html is apparently not advisable because the package dependencies that show up after the zypper in *.rpm command are difficult to resolve. An alternative is to compile the source code locally after downloading it from https://github.com/zeroc-ice/ice/releases/tag/v3.6.4: To avoid an error message cannot find -lmcpp further down check that the mcpp library is in- stalled: zypper install mcpp-devel Note that mcpp-2.7.2 is known to be buggy when slice2py is used to handle slice files that contain C++ trailing comments that start with two slashes. 3 So either

use only the C-type comments /* .... */ • or use the C++-style comments only if the entire line in which they appear can be removed • without changing the meaning of the source code;

build your patched version of the mcpp library according to https://forums.zeroc.com/ • discussion/comment/35232;

2A bug that exists for more than a decade https://bugzilla.redhat.com/show_bug.cgi?id=191497 3The basic problem is actually not within mcpp but the fact that slice2py does not call mcpp including the option -+ which enables C++ style comments. LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 9

remove the comments with your own preprocessor before offering the *.ice files to the slice • programs:

cpp -finput-charset=US-ASCII -P -fpreprocessed -E -std=c99 my.ice.in > my.ice

Starting with ice 3.6.4 you also need zypper install lmdb-devel

# git clone https://github.com/zeroc-ice/ice.git tar xzf ice-3.6.4.tar.gz cd ice-3.6.4 cd cpp vi src/Makefile # if 3.6.2 add slice2py to the second block of SUBDIRS CXXFLAGS=-O2 prefix=$HOME make install cd ../python vi config/Make.rules* # change the PYTHON to PYTHON3.4 version if needed # may need zypper install patterns-openSUSE-devel_python3 CXXFLAGS=’-O2 -Wno-int-in-bool-context’ prefix=$HOME make install

Java support is trickier because the installation requires an online Internet connection: export JAVA_HOME=${HOME}/jdk-9 # if not yet set to an existing value # ensure the https (!) proxies are known: export _JAVA_OPTIONS=’-Dhttps.proxyHost=web-proxy.mpia-hd.mpg.de -Dhttps.proxyPort=3128’ # put db.jar into /usr/share/java: zypper install libdb_java-4_8-devel cd ../java CXXFLAGS=-O2 prefix=$HOME make install

Finally

set the ICEDIR environment variable in /.bash login to the prefix directory used above to • avoid that the ice.m4 macros of TAN look only at some other standard places.

add $ICEDIR/lib64 or wherever the ICE library was installed to the LD LIBRARY PATH of • Section 2.1.

add $ICEDIR/python or wherever the ICE library was installed to the PYTHONPATH of Section • 2.1.

2.6 Compilation

Being already in the directory TwiceAsNice call rm -rf ${INSROOT}/lib/* ${INSROOT}/lib64/* ${INSROOT}/include/* \ ${INSROOT}/slice/* ${INSROOT}/bin/* make clean 10 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044

2.6.1 Patches

1. At this points one needs to edit all python.m4 files if one wants to use any Python version higher than 2.6. This can be done with a global edit like

pfil=$(find . -name python.m4) for f in ${pfil} ; do sed -i ’s/in python2.8/in python3.4m python2.8/’ $f sed -i ’s/="python2.6/="python3.4 python2.6/’ $f sed -i ’s/="python2.7/="python3.4 python2.7/’ $f done export PYTHON=python3.4 alias python=$PYTHON # in ~/.bashrc pip3.4 install pexpect

This will still most likely fail unless the boost python wrapper has not been configured in the user-config.jam file to use that newer python version.

2.6.2 Installation

2.6.2.1 TAN Compile TAN first: cd lnsw/TwiceAsNice make install -j -l 2 |& tee install.log Starting in 07/2017, the lead software engineer decided that the sofa and skymaker software supporting the LN software must no longer be compiled by default with the rest of the software. It now is necessary either

to compile it beforehand in an extra step: • cd lnsw/ln/3rdparty autoreconf -f -i -s ./configure --prefix=$INSROOT make install

or to edit lnsw/ln/Makefile.am and to insert 3rdparty in front of the objects list, before • laos-adsecIF.

Starting in 07/2017, ds9 is used to create simulated images in the GWS plane; it can be installed according to the instructions in Section A.6 of [1]. If (under openSUSE Leap 15.0) a complaint appears that -lnsl cannot be linked to, because the library is missing, this may be caused by a missing link to libnsl.so in the directory of libraries. This can be patched with cd /usr/lb64 ln -s lbnsl.so.2 lbnsl.so LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 11

2.6.2.2 LN software Then compile the bulk of the LN software: cd ../ln make install -j -l 2 |& tee install.log We avoid being stuck in potential bugs in the checks by not calling the simpler make -j. If the configure scripts complain about missing config/compile files, go to the associated directory with the configure.ac file and call autoreconf -i there to continue.

2.6.2.3 Drivers The driver for the CCD’s [2] is obtained from https://edt.com/file-category/ pdv/. The driver for the reflective memory card is obtained after registration from https://www. abaco.com/download/rfm2g-linux-3264-bit-pciepcipmc-driver-x86-kernels-r0900. mv EDTpdv-5.5.3.-7.noarch.rpm /opt cd /opt export CFLAGS=’-shared -fPIC’ export LDFLAGS=’-shared -fPIC’ rpm -i EDTpdv*.rpm make all make libpdv.so If it is not found at compile time, some TAN libraries like libBasdaVinoDeviceLittleJoeVin- oDevice will not be build. If the operating system has been upgraded with either zypper up or yum up, one must recompile the EDT and reflective memory drivers, at least on laos2 where the corresponding services are run: cd /opt/EDTpdv ; make driver cd /opt/rfm2g ; make install ; ./rfm2g_load ; ./rfm2g_init start The simplest way to re-load the drivers is to reboot the computer. Afterwards the output of lsmod should list edt and rfm2g. On lircs, and in principle also on its backup lsys2, the PLX driver and GEIRS should also be recompiled after each upgrade of the operating system. Details are in [1]. The short version is cd $HOME/GEIRS/trunk ./INSTALL.plx make -f Makefile clean ./INSTALL

2.6.2.4 Developpers If monit is run under an account not equal to lneng, update the monit configuration to use the correct INSROOT: cd lnsw/config autoreconf -f -i -s configure To develop software when the hardware is absent, run the script in lnsw/config/makeDummydevCfg.pl 12 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 and lnsw/config/makeLocalhostCfg.pl to let the libraries use device drivers in simulating mode and to let them all run on your local workstation.

3 CONFIGURATION

3.1 IIF FITS Header Keywords

The translation of the TCS/IIF dictionary entries to FITS header keywords is configured in config/ltcs/ltcs.iif-fits.xml. The file is also the basis of which dictionary entries are polled regularly by the LN and available for status information with commands like liifSnapshotGUI. Apart from XML comments this contains a long vector of specifications. The attributes of a dic entry are: dd The data dictionary keyword exactly as used in the ICE interface. The two-sided keywords that start with S will be dynamically dispersed into one-sided keywords by the ltcs software depending on whether LINC is registered on the SX, the DX or both sides of the telescope. type The type of the FITS header card. This must be one of float, bool, long, string, double or int unit The unit of the value of the keyword, following FITS standards [3]. Note that this is almost always different from the units used internally within the IIF specification (which is not FITS compliant). This may be the empty string, which usually indicates that these are counts or that the variable is of boolean type. com The string in the FITS comment, excluding the unit. keyw The FITS keyword. Note that all of these are currently restricted to 8-letters because LBTO argues it cannot handle keywords with the HIERARCH convention. use This is either true (the default if the attribute is absent), false or cmt.

true means the corresponding dictionary entry becomes a FITS header card. • false means the corresponding dictionary entry is discarded. • cmt means the corresponding dictionary entry becomes a COMMENT header card. • If use is cmt or false, the keyw attribute may be missing.

3.2 ICS FITS Header Keywords

The information of the TAN property tree which are translated to FITS header cards are config- ured in the various files of config/lircs/geirs/* in the (undocumented) TAN format. Each of the CFG.DATA.i.CONNECT specifies a server name and a node in the property tree. The CFG.DATA.i.NODE specifies whether that node is to be prepended to each of the branch specifications of CFG.DATA.i later on. The CFG.DATA.i itself is a list of lists. These sublists contain four strings, in that order:

The name of the leaf in the property tree (after prefixing with the node). • LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 13

Some name of a server on which the device handler may run; this entry is not actually needed • but appended in the comment portion of the FITS header card.

The FITS header keyword. Dots in that specification will be replaced by blanks by the • interface. HIERARCH LBTO LN will always be added, so it must not be part of the configuration.

The unit of the value, compatible with the FITS standard [3]. If the property has an attribute • named UNIT, the server will use the online value of the attribute in the property tree, actually overriding that 4th entry.4

3.3 Port numbers

The ports of various servers in use for TAN might be extracted from the configuration file cd lnsw/config find . -type f -exec fgrep -H ’PORT=’ {} \; | fgrep -v .svn | fgrep Endpoint \ | grep -E -v -e ’(alias-mpia|alias-localhost)’ \ | awk -F ’PORT=’ ’{printf "%d %s\n",$2,$0}’ | fgrep -v ’:#’ | sort -n As of 2018-11-23 we have

port config file service 10000 /alias-lbt.cfg lbto.iifSimulator-svr.ALIAS 10000 /laos/sx/hws/wfc/laos.sx.hws.wfc.loop.float-sim.cfg ADAPTER 10000 /ltcs/ltcs.iif-svc.cfg IIF.SVC.CFG.CONNECTION 10000 /ltcs/ltcs.iifDummyLocalhost-svc.cfg IIF.SVC.CFG.CONNECTION 10000 /ltcs/ltcs.iifDummyTucson-svc.cfg IIF.SVC.CFG.CONNECTION 10001 /laos/sx/hws/wfc/laos.sx.hws.wfc.fitsLoop-svr.cfg ADAPTER 10002 /laos/dx/hws/moe/laos.dx.hws.moe.maps-svr.cfg ADAPTER 10010 /alias-lbt.cfg laos.sx.hws.drot.derotation-svr.ALIAS 10017 /laos/dx/gws/moe/laos.dx.gws.moe.magicLantern-svr.cfg ADAPTER 10020 /alias-lbt.cfg laos.sx.hws.moe.warmOptics-svr.ALIAS 10030 /alias-lbt.cfg laos.sx.hws.moe.sensor-svr.ALIAS 10040 /alias-lbt.cfg laos.sx.hws.moe.calibrationUnits-svr.ALIAS 10050 /alias-lbt.cfg laos.sx.hws.se.starEnlarger-svr.ALIAS 10072 /alias-lbt.cfg laos.sx.hws.aoc.ccdtrack-svr.ALIAS 10074 /alias-lbt.cfg laos.sx.hws.aoc.secenter-svr.ALIAS 10080 /alias-lbt.cfg laos.sx.hws.wfc.loop-svr.ALIAS 10100 /alias-lbt.cfg laos.sx.gws.se.starEnlarger-svr.ALIAS 10110 /alias-lbt.cfg laos.sx.gws.moe.sensor-svr.ALIAS 10115 /alias-lbt.cfg laos.sx.gws.moe.annularMirror-svr.ALIAS 10120 /alias-lbt.cfg laos.sx.gws.moe.magicLantern-svr.ALIAS 10130 /alias-lbt.cfg laos.sx.gws.drot.derotation-svr.ALIAS 10150 /alias-lbt.cfg laos.sx.hws.wfc.recmat-svr.ALIAS 10151 /alias-lbt.cfg laos.dx.hws.wfc.recmat-svr.ALIAS 10152 /alias-lbt.cfg laos.sx.gws.wfc.recmat-svr.ALIAS 10152 /laos/sx/gws/wfc/laos.sx.gws.wfc.recmat.working-svr.cfg ADAPTER 10153 /alias-lbt.cfg laos.dx.gws.wfc.recmat-svr.ALIAS 10154 /alias-lbt.cfg laos.sx.gws.aoc.ccdtrack-svr.ALIAS 10156 /alias-lbt.cfg laos.sx.gws.aoc.secenter-svr.ALIAS

4It is not sufficient to have another leaf named UNIT for this to happen, it must be an attribute of the leaf that contains the value. Unfortunately some deletionists are known to delete these attributes, so we cannot make this a standard. . . 14 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044

10180 /alias-lbt.cfg laos.sx.gws.wfc.loop-svr.ALIAS 10210 /alias-lbt.cfg laos.dx.hws.drot.derotation-svr.ALIAS 10220 /alias-lbt.cfg laos.dx.hws.moe.warmOptics-svr.ALIAS 10230 /alias-lbt.cfg laos.dx.hws.moe.sensor-svr.ALIAS 10240 /alias-lbt.cfg laos.dx.hws.se.starEnlarger-svr.ALIAS 10250 /alias-lbt.cfg laos.dx.hws.moe.calibrationUnits-svr.ALIAS 10262 /alias-lbt.cfg laos.dx.hws.aoc.ccdtrack-svr.ALIAS 10264 /alias-lbt.cfg laos.dx.hws.aoc.secenter-svr.ALIAS 10270 /alias-lbt.cfg laos.dx.hws.wfc.loop-svr.ALIAS 10290 /alias-lbt.cfg laos.sx.moe.hatch-svr.ALIAS 10295 /alias-lbt.cfg laos.dx.moe.hatch-svr.ALIAS 10300 /alias-lbt.cfg laos.dx.gws.se.starEnlarger-svr.ALIAS 10310 /alias-lbt.cfg laos.dx.gws.moe.sensor-svr.ALIAS 10312 /alias-lbt.cfg laos.dx.gws.aoc.ccdtrack-svr.ALIAS 10314 /alias-lbt.cfg laos.dx.gws.aoc.secenter-svr.ALIAS 10320 /alias-lbt.cfg laos.dx.gws.moe.annularMirror-svr.ALIAS 10330 /alias-lbt.cfg laos.dx.gws.drot.derotation-svr.ALIAS 10380 /alias-lbt.cfg laos.dx.gws.wfc.loop-svr.ALIAS 11001 /alias-lbt.cfg ltcs.iifDummyLocalhost-svr.ALIAS 11002 /alias-lbt.cfg ltcs.iifDummyTucson-svr.ALIAS 11003 /alias-lbt.cfg ltcs.iif-svr.ALIAS 13001 /laos/dx/gws/adsec/laos.dx.gws.adsec-svc.cfg LOOP 13001 /laos/sx/gws/adsec/laos.sx.gws.adsec-svc.cfg LOOP 20010 /alias-lbt.cfg lsys.cab.ps-svr.ALIAS 20105 /laos/dx/hws/wfc/laos.dx.hws.wfc.fitsLoop-svr.cfg ADAPTER 20201 /alias-lbt.cfg lircs.moe.fwr-svr.ALIAS 20202 /alias-lbt.cfg lircs.moe.dwr-svr.ALIAS 20203 /lircs/envm/ENVM server.cfg ADAPTER 20204 /alias-lbt.cfg lircs.moe.dpos-svr.ALIAS 20205 /alias-lbt.cfg lircs.moe.drot-svr.ALIAS 20215 /alias-lbt.cfg lircs.fits-svr.ALIAS 20221 /alias-lbt.cfg lircs.moe.smc-svr.ALIAS 28511 /alias-lbt.cfg lircs.geirs-svr.ALIAS 36432 /laos/sx/hws/se/laos.sx.hws.se.starEnlarger-sim.cfg ADAPTER 40000 /laos/sx/hws/moe/laos.sx.hws.moe.hatch-svr.cfg ADAPTER

There is no overlap with the standard GEIRS CAMSERVERPORT, CAMSTATUSPORT, CAMDATAPORT and CAMICEPORT which are by default in the range 28502–28511. Of course one should be very careful not to use the same port for two different services that may run at the same time on the same computer!

4 Linc-Nirvana

4.1 Angles

4.1.1 Standard Spherical Astronomy

Let

A be the pointing azimuth. Beware of different sign conventions in different publications. We • use the offset North=0, East= 90 deg as in the IIF of the LBTO, xephem and astropy; this LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 15

differs from the ESO standard by 180 deg. Note that in the second edition of [4] the text said that A was measured from south, but the formulae given were measuring A from north; this has been corrected in the third edition. a be the pointing altitude above the horizon. z = π/2 a the zenith angle. We call A and a • − the coordinates in the horizontal coordinate system. φ the geographic latitude of the observatory. • λ the geographic longitude of the observatory. • p be parallactic angle, the position angle of the zenith, in the standard sign convention. The • angle by which the direction from the star along +δ must be turned ccw in the non-flipped image to get the direction +a [5][6, p. 50]. α the right ascension of date. • δ the declination of date. We call α and δ the coordinates in the equatorial system. • h the hour angle, • l the local sidereal time, l = h + α. • Then [7] cos a sin A = cos δ sin h; (1) − cos a cos A = sin δ cos φ cos δ cos h sin φ; (2) − sin a = sin δ sin φ + cos δ cos h cos φ; (3) cos δ sin h = cos a sin A; (4) − cos δ cos h = sin a cos φ cos a cos A sin φ; (5) − sin δ = sin a sin φ + cos a cos A cos φ. (6) This system of equations can be written as a rotation around the equatorial pole by the angle l equivalent to the local sidereal time, followed by a tilt of the equatorial plane by φ:       cos a cos A sin φ 0 cos φ cos δ cos h −  cos a sin A  =  0 1 0   cos δ sin h   −   −  ·  −  sin a cos φ 0 sin φ sin δ       sin φ 0 cos φ cos l sin l 0 cos δ cos α − =  0 1 0   sin l cos l 0   cos δ sin α  . (7)  −  ·  −    cos φ 0 sin φ 0 0 1 sin δ If A is measured south over west as in [8,9,5] and in wikipedia, the signs in front of all cos A and all sin A need to be reversed. These equations assume that atmospheric dispersion effects are neglected and that the equatorial coordinates are precessed to the date of the observation. Note that (following experiments with the telescope simulator) the α-δ coordinates obtained from the data dictionary of the TCS are not precessed that way but only propelled with respect to proper motion.5 The LN software is currently copying these data from the telescope, including the EQUINOX, to the FITS headers.6 5The associated description in http://wiki.lbto.org/bin/view/Instrumentation/ UsefulDataDictionaryVariables seems to be incorrect, unless the telescope software on the mountain differs from the one of the simulator. . . 6this may violate FITS standards that propose that the EQUINOX should be compatible with the coordinates. It 16 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044

4.1.2 Parallactic Angle

The parallactic angle is the angle by which the great circle through the star and the NCP must be rotated to become the great circle through the star and the zenith. It is the dihedral angle between the two planes that contain the great circles and the global center of coordinates. It is computed by placing the star at the Cartesian coordinates   cos δ cos α   s =  cos δ sin α  (8) sin δ of the equatorial coordinate system. The NCP is at   0   N =  0  . (9) 1

The vector z to the zenith is given in the same coordinate system by inserting a = π/2, cos a = 0 into (7) and multiplying from the left by the inverse matrix:

   −1     sin φ 0 cos φ cos l sin l 0 0 cos φ cos l − z =  0 1 0   sin l cos l 0   0  =  cos φ sin l  . (10)  −  ·  −  ·     cos φ 0 sin φ 0 0 1 1 sin φ

Technically this is easy because the matrices are rotation matrices which have inverses which are the transpose. The cross product s z (normalized to unit length by dividing through sin z) is the × rotation axis to move the star to the zenith   cos δ sin α sin φ sin δ cos φ sin l 1 1 − ωz = (s z) =  cos δ cos α sin φ + sin δ cos φ cos l  . (11) sin z × sin z  −  cos δ cos φ sin(α l) −

Finally ωz s is the third orthogonal axis and the initial direction into which the star is moved on × the great circle to the zenith—not reproduced in full detail here:

1 1 2 1 ωz s = (s z) s = [zs s(s z)] = (z cos z s). (12) × sin z × × sin z − · sin z −

The plane tangential to the celestial sphere at the star is spanned by the unit vectors to the north,   sin δ cos α − uδ =  sin δ sin α  (13)  −  cos δ and to the east,   sin α  −  uα =  cos α  , (14) 0 has some benefit; one can search for targets in the FITS files and these won’t change over time comensurate with precession. . . LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 17

3 2 1 p (rad) 0 -1 -2

1.5-3 1 0.5 δ (rad) 0 -0.5 -1 -1.5 -1 0 1 2 3 -3 -2 h (rad)

Figure 1: The parallactic angle p as a function of hour angle h and declination δ with (18) for geographic latitude φ of the LBTO. Depending on the polar distance π/2 δ, transit through the − meridian (h = 0) means the parallactic angle p either wraps around π +π or it runs through − → zero. See [12, Fig. 2.4]. obtained by differentiationg (8) with respect to δ and α and normalizing to unit length (see e.g. [10]). The parallactic angle p is the angle north-over-east of the initial section,

ωz s = cos puδ + sin puα. (15) ×

By multiplying with uδ and uα, and utilizing uδ uα such one of the two dot products on the ⊥ right hand side vanishes [11, 71]: § 1 (ωz s) uδ = cos p = [cos δ sin φ sin δ cos φ cos h]; (16) × · sin z − 1 (ωz s) uα = sin p = sin h cos φ. (17) × · sin z This can be evaluated with the usual atan2 functions; the sin z factor can be dropped because it is always positive and cannot switch the quadrants of the angle. The same sign-argument applies to the factor cos φ, so we end up with the textbook expression[12, Eq. (2.1)] sin p sin h tan p = = . (18) cos p cos δ tan φ sin δ cos h − The time derivative of the parallactic angle is given by implicit derivation with respect to time: cos φ cos A p˙ = h,˙ (19) − sin z 18 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044

3 2 1 p (rad) 0 -1 -2

1.5-3 1 0.5 δ (rad) 0 -0.5 -1 -1.5 -1 0 1 2 3 -3 -2 h (rad)

Figure 2: The parallactic angle p as a function of hour angle h and declination δ with (18) for geographic latitude φ of the LBTO. The difference to Fig.1 is: the patches of the surface where the elevation a, where the sine of (3) is negative and the star is not visible—have not been plotted. LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 19 where h˙ 2π 1.002737/(24 3600) rad/s is the time derivative of the hour angle, a full circle in a ≈ × × sidereal day. Note that [12, Eq. (2.2)] uses a different sign because it uses ESO’s convention of az- imuths A. These functions are implemented in the SkyPoint class in nice/src/libNice/Nice/Map.

4.1.3 LBTO Coordinate System

Consider the telescope pointing to the south on the meridian, SX and DX aligned East-West along the azimuth, and two bundles of rays approaching the telescope, the first an on-axis star in the zenith, and a second bundle of light from a star closer from the zenith. The bundle from the star closer to the zenith has an inclination to the S before hitting M1; its image in the primary focus is south from the image of the on-axis star. Moving up to M2, the second star has a inclination south compared to the on-axis star, and moving down on to M3 an inclination closer to the zenith than the on-axis star. If one wanted to create an image in a focal plane where the image in the focus after M3 shows the off-axis star up from the on-axis star, one would need to point M3 south, such that the incidence angle of the off-axis star on M3 is smaller than the incidence angle of the on-axis star. The reference cameras where North is “up” in the Gregorian foci are south of M3, both for SX and for DX. This is an effect of the primary focus below M2 due to the “fast” optics of M1 of the LBT. Each transition through a focal plane induces a 180◦ image rotation. For more standard M1-M2 curvatures, where the primary focus is after M3, that camera would need to be North of M3. Note that reference systems pointing “from the instrument to M3” or “along the beam toward the detector” are not distinguished: a detector or Kodachrome film held in that (second) focal plane defines an unambiguous image with a two-dimensional coordinate system on the front. The detector surface always faces the beam.7 We will use the standard astronomical sign convention that the image is called non-flipped if its handedness is the same is if looking with the bare eye at the sky. In non-flipped images one reaches the direction of +α by turning a vector at the star position pointing to +δ by 90◦ ccw. (A, a) is a right-handed coordinate pair in non-flipped images. (δ, α) is a right-handed coordinate pair in non-flipped images. The images in the prime focus below M2 and the images by the camera in the Gregorian (second) foci are non-flipped. The usual even-odd rule applies:

In a mirror train of plane mirrors the image flips sign if the number of surfaces is odd. • Actually the component of the image in the incidence plane flips its sign, the other orthogonal component keeps its sign. If the camera keeps its “up” definition orthogonal to the common set of incidence planes, each mirror triggers a left-right flip in the image. Each transition through an image plane rotates the image by 180◦, but does not flip. • At first view it appears puzzling that that images in the LBT Gregorian instrument focal planes are not flipped, although light has passed through an odd number of mirrors (M1, M2, M3) up to there. The apparently missing flip is the one introduced when no longer looking at the sky up the light beam but looking down the beam at the images of the cameras.

7There are other LN documents around that look through some transparent detector plane on the sky and draw ad-hoc axes on the observers side, on the back plane of the detector; their conclusions on image flips and coordinate systems differs from the ones here in signs, but not in substance. 20 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044

+A SX −A DX

+δ −108.5 +108.5 p

+a

p +a +A +δ −A

Figure 3: Image orientation of a camera in the instrument focus after M3. The direction of the ◦ altitude +a axis is Rz = 108.5 away from the up +z direction. The image is not flipped. If the ± time derivative of the parallactic angle isp ˙ > 0, the image rotates cw on both arms, because the (a, A) axes are fixed in the image plane for the LBT mount. In a video of the figure, the +δ arrow rotates cw.

In the telescope coordinate system fixed to the mount, +z points towards the star, +x points from DX to SX, and +y points to the gallery [13]. The two cameras of zero-rotated images had to be placed in the y direction, at the (non-bent) Gregorian front. There actually are no instruments − there. The positions of instruments (still using the notation of the telescope coordinate system with right-handed angles Rz opposite to the direction of increasing azimuths) of the focal stations relative to that virtual camera position are  90◦ 26.5◦ = +63.5◦, LUCI DX  −  63.5◦, LUCI SX  −  +90◦, LBTI, SHARK DX Rz = ◦ (20)  90 , LBTI, SHARK SX  ◦ ◦ − ◦  90 + 18.5 = +108.5 , LN DX   108.5◦, LN SX − If the reference detector rotates with M3, the direction of N in the image rotates ccw with +Rz; a camera placed at the focus behind the annular mirrors experiences image rotations as in Figure3. 8

! ! ! ∆x cos Rz sin Rz cos a∆A = sF − . (21) ∆y sin Rz cos Rz ∆a F · This defines the matrix that converts topozentric horizontal coordinates to instrument focal coor- dinates: ! cos Rz sin Rz AT →F sF − . (22) ≡ sin Rz cos Rz

8 ◦ The PCS keeps the value of |Rz| + 180 = 288.5 in the LEFTIAA and RIGHTIAA parameters in some configuration file. LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 21

The plate scales, variables F SCALE in config/laos/*/gws/se/starEnlarger-svc.cfg, are ( 601.75µm/as,SX; s = (23) F 600.6µm/as,DX.

The transformation between (α, δ) and (A, a) is a passive transformation; the targets on the detector do not move but the coordinate axes are rotated instead. The a-axis is found by rotating the δ-axis by the parallactic angle p. ! ! ! cos a∆A sin p cos p ∆δ = − . (24) ∆a cos p sin p · cos δ∆α

So we define ! sin p cos p AE→T − (25) ≡ cos p sin p as the transformation matrix to transform equatorial coordinates to topozentric horizontal co- ordinates. The WCS convention needs that equation in a left-handed (α, δ) system, not in a right-handed (δ, α) system. The associated matrix determinant on the right-hand side is negative: ! ! ! cos a∆A cos p sin p cos δ∆α = − . (26) ∆a sin p cos p · ∆δ

Multiplication with the inverse matrix from the left yields ! ! ! cos p sin p cos a∆A cos δ∆α − = . (27) sin p cos p · ∆a ∆δ

The matrix that rotates points in the (δ, α) system into the non-rotated image system glued to the platform at the instrument focus after the annular mirror is a rotation with (24) into the (A, a)- system and then a rotation that increases angles by Rz from the (A, a)-system to the platform: ! ! ∆x ∆δ = A A . (28) ∆y T →F E→T cos δ∆α F · ·

! cos φ0 sin φ0 AT →F AE→T = AE→F = sF − , (29) · sin φ0 cos φ0 where the direction to +δ relative to the horizontal coordinate is given by

◦ φ0 = Rz p + 90 , (30) − and RZ is given by (20) and p the parallactic angle.

4.1.4 Nominal Angles

Many of the GUI’s of the instrument display angles that are derived from motor steps/counts by scaling and offset factors defined in the services BASDA configuration files. These will be called nominal angles, and are not necessarily related to angles in image planes or angles related to the orthogonal coordinate system of the bench. The reasons for these discrepancies are the standard ones: 22 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044

the offsets have not been calibrated yet, for various reasons, including lack of interest or the • unavailablility of light sources and detectors that would measure inclinations along partial paths; there are people who think that changing offset angles in the database —meant to catch • these offsets from misalignments, arbitrary motor switch positions and so on—should not be done to avoid backwards incompatibilities. Some reconstruction matrices are for example tabulated for some discrete set of angles and need to be re-labelled if offset or signs change and if the matrices are applied based on angles in the database.

One example: for some reasoning that has probably been lost, looking from the annular mirror toward the GWS, increasing the nominal angle turns the device ccw for SX, whereas increasing the nominal angle turns the device cw for DX. This is actually induced by two different signs of the multipliers 0.00125 for the conversion from angles to motor steps in laos.dx.gws.drot.bearing- ± dev.cfg and laos.sx.gws.drot.bearing-dev.cfg.

4.1.5 Derotator Angles

Derotation of images while integrating on a detector happens

passively (in the sense of linear algebra) by rotating the entire GWS or infrared detector, • which is equivalent to rotating the coordinate system by the negated angle of the motorized service, actively by rotating the beam with the K-mirrors for the HWS. • Effectively this induces a sign flip of the motor angles depending on whether GWS or HWS or science camera images are derotated. Time derivatives of derotator angles read from the IIF have the opposite sign of the time derivatives of the parallactic angle, see Section 4.5.2. The effective total product of these sign flips (polynomials to parallactic angle, active versus passive, ad-hoc conventions in motor software and geometry) determines which sign should be applied to convert derotator polynomials to motor steps or counts. That sign is the sign of SVC.CFG.DIRECTION in the five drot-svc.cfg configuration files. Note:

1. The parallactic angle may increase or decrease with time. This sign of the first derivative is imprinted in the trajectories received from the IIF and does not to be considered by the derotator software. 2. The derotator services do not use the scaling factors of the configuration database mentioned above. So changing their signs would change the nominal angles but not the sense of rotation of the derotator services. 3. Sky rotation of SX and DX has the same sense, since the two coordinate systems in Figure 3 have the same orientation. Although the two optical trains of SX and DX are mirror symmetric relative to the y-axis, the direction to east is the global one, and this sort of symmetry-breaking implies that GWS and K-mirror bearings have the same sense of rotation for SX and DX. LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 23

4.2 Orientation of patrol camera images

4.2.1 Calibration

The pixel scale on the CCD47-20 patrol cameras is [14, p 7]

−5 −7 sP 0.144arcsec/pix = 4 10 deg/pix = 6.981 10 rad/pix. (31) ≈ × × This value is stored in the PIXSCALE properties in units of degrees in lnsw/config/laos both in dx/hws/pcam/laos.dx.hws.pcam.ccd47-svr.cfg and in sx/hws/pcam/laos.sx.hws.pcam.ccd47- svr.cfg. The usual FITS coordinate system puts the center of the K-mirror rotations at some (xP c, yP c) coordinate. Unless calibrated, the first approximation is xP c = yP c = 512.5 pix, the center of the CCD. The values reported in the Com-3 version of [15, p 47] are ( (485, 421),SX; (x , y ) = (32) P c P c (488, 414),DX.

The translations and rotations (∆x, ∆y) used further down are measured with respect to that center of rotation. Rotations are described by angles β as currently used in the instrument control software, which means they are measured in units of the K-mirror axis rotations; further down we generally need the beam rotations 2β, doubled values. In PC1 the action of K-mirror rotations was measured on the two cameras. On SX and DX a positive rotation (defined as increasing the number of steps of the motor, not by any signed angle of opto-mechanics on the table) rotates the image clockwise. (I added the algebra which determines the center of rotation to the wikipedia article.) As such these data are insufficient to map sky coordinates to patrol camera coordinates, because

The cameras are on motorized stages that can be moved laterally, and these positions need • to be combined to construct the expected center coordinates,

tilted axes of the K-mirror lead to the effect that the (xc, yc) are functions of the K-mirror • angle, which means to first order that centers move on circles as a function of β. Perhaps this can be calibrated off-sky with the auxiliary light sources, see Ticket 1434.

The beam splitter optical thickness may have an effect of moving the centers sideways. See • Ticket 1419 for plans of exchanging them.

In PC1 the motion of the target was measured on both cameras if A were changed by +10◦ or a ◦ (0) ◦ (0) ◦ were changed by 10 , at nominal positions of the K-mirrors, βSX = 3.66 and βDX = 81.46 . The − (0) ◦ (0) ◦ targets moved by angles φSX = 107.5 (Figure4) and φDX = 82.9 (Figure5). The object moved almost up in the image when the telescope pointed closer to the horizon; so the altitude axis points almost up in these two patrol camera images. 9 In a derotated reference snapshot one would use A as the horizontal coordinate and a as the vertical coordinate. This (A, a) coordinate system is flipped with respect to the (x, y) image coordinates for

9Some comments in the original blogs of 2016-11-24 indicate otherwise, but this turned out to be a misinterpretation of a sign in a TCS command for elevation changes (J. Hill, priv. commun. 2017-02-23.) 24 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044

(0) Figure 4: On the SX side a negative change of the elevation moves the object into the φSX direction. The image shows the sum of the 10 images before the move subtracted from the sum of the 10 images after the move. LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 25

(0) Figure 5: On the DX side a change of the elevation moves the object into the φDX direction. The image shows the sum of the 10 images before the move subtracted from the sum of the 10 images after the move. 26 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 both cameras,10 so the 2D rotation matrix that transforms between the two systems has a negative determinant; the images on the patrol cameras are flipped and rotated. A (virtual) camera at the instrument focus after the annular mirror is not flipped, and there is an odd number of 7 further reflections in the path before arriving at the patrol cameras:

1. DM2,

2. DM3,

3. piston mirror,

4. the dichroic that reflects the beams towards +y at an angle of approximately 7◦,

5. K-mirror K1,

6. K-mirror K2,

7. K-mirror K3.

We may estimate the effect of the piston mirror and warm dichroics as follows: The beam direction before hitting the piston mirror is horizontal with an angle of 18.5◦ relative to the x axis of the LBT coordinate system. We guess that the piston mirrors reflect the two beams strictly into the z − direction (although no such numbers appear to in the optical design documents), and then guess with a ruler from [16, Fig. 1] that the beams are reflected towards the two K-mirrors at angles of 8.5◦ relative to the +y axis. The net effect of these two reflections is a rotation of the beam by 80◦ (SX) or by +80◦ (DX), without flip, always measuring angles on detectors facing the beams. − The K-mirror flips the component in its incidence plane. (It actually are three flips in the common incidence plane combined into one.) Before arrival at the first of the three mirrors of the K- mirrors, we project the star coordinates with (29) into the platform x-y coordinates and then with a passive rotation—rotation by the negative K-mirror angle m(β +β0)— such that the second “up” component of the vector at the right of that matrix operator is in the common incidence plane of the three mirrors. Then flip the second component three times, but write down only one of the three (1, 1) matrices because the product of two of them is the unit matrix: − ! ! 1 0 cos[ m(β + β0)] sin[ m(β + β0)] − − − . (33) 0 1 · sin[ m(β + β0)] cos[ m(β + β0)] − − −

β0 incorporates the effect that the nominal angles of the K-mirror motors are are not aligned with the horizontal coordinate system of the bench. After the last mirrors of the K-mirror we de-rotate with the inverse matrix to measure components again in the bench’s x-y system that does not depend on the K-mirror angle, ! cos[m(β + β0)] sin[m(β + β0)] − . (34) sin[m(β + β0)] cos[m(β + β0)]

The combined effect of the K-mirror is the product of these 3 matrices: ! cos[2m(β + β )] sin[2m(β + β )] 0 0 . (35) sin[2m(β + β0)] cos[2m(β + β0)] − 10The fact that the handedness of the (A, a) system on both sides is the same is compatible with the equal handedness of the two axes in the PCS coordinate system, Fig. 6 and Fig. 8 in [13]. LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 27

The appearance of the factor 2 in the arguments of the trigonometric functions illustrates that the beam rotates by 2β if the K-mirror axis rotates by β. At nominal angle of 0◦ the two K-mirrors should be at their negative limit switches, so the SX K-mirror reflections should be (almost) in the horizontal plane, and the DX K-mirror reflections (almost) in the vertical plane [17, Fig. 14]. Because according to eye witnesses the “almost up” positions are 3◦ (SX) and 87◦ (DX), we assume for the following analysis that [17, Fig. 14] is ≈ ≈ erroneous: it shows the positive and negative limit switches effectively swapped (as if their cables in the electronics had been swapped). In that case increasing the nominal motor angles means rotating the K-mirrors cw (looking down the beam observed from the warm dichroic), and rotating the patrol camera images also cw, ( 1, HWS SX, m = − (36) 1, HWS DX. − This sign is equivalent to the negative slope in [18, Fig. 17]. Inside LN, the coordinate transformation between (A, a) and (x, y) in the Patrol Cameras is a cascade of transformations. The first is a combined rotation by the first four static mirrors in the bullet list above, a hybrid of the angles by which the elements are mounted on the bench. The second is the beam flip-rotation of 2m(β + β0) by the K-mirror. We assume that read-out-directions of detectors are the “natural” ones and do not introduce further flips, only rotations; they are only represented by a homogeneous scale factor sP plus shifts (32). The four reflections are accumulated in a total angle φ—which differs between SX and DX. ! ! ! ! ∆x cos φ sin φ cos[2m(β + β0)] sin[2m(β + β0)] cos a∆A sP = − ∆y sin φ cos φ · sin[2m(β + β0)] cos[2m(β + β0)] · ∆a P − ! ! cos[φ + 2m(β + β )] sin[φ + 2m(β + β )] cos a∆A = 0 0 , (37) sin[φ + 2m(β + β0)] cos[φ + 2m(β + β0)] · ∆a − We have written cos a∆A to account for the shrinking of the horizontal scale as we point closer to the zenith. The task of the calibration is to find φ for both sides given correlated measurements of telescope motions (∆A, ∆a) and image motions (∆x, ∆y) on the patrol camera. The calibration takes for example the run with ∆A = 0, so (37) becomes

sP ∆x = sin[φ + 2m(β + β0)]∆a; (38)

sP ∆y = cos[φ + 2m(β + β0)]∆a. (39) − The ratio ∆y/∆x yields for the direction of the A-axis on the patrol cameras:

(0) (0) tan φ = cot[φ + 2m(β + β0)]. (40) − From the reference values cited above we deduce ( 155.18◦,SX, φ + 2mβ0 = − (41) 24.81◦,DX. − The offset was also calibrated implicitly by considering the images of the fiber plates on the patrol camera [18]. A point on the negative horizontal axis in Figure3 (the positive horizontal axis in 28 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044

[18]) appears in the patrol camera images at an angle of ( 279.63 360 = 80.37◦, SX; γ0 = − − (42) 266.38 360 = 93.62◦, DX; − − relative to the horizontal axis, if the K-mirror angle is nominally 0◦ and if there is a zero offset in the CFG.TRANS.DEGREE in the kMirror-dev.cfg file. −1 The starting coordinate system is this time the focal plane, so plugging the inverse AF →E = AE→F of the Rz matrix of (29) into (37) yields ! ! ! ! ∆x cos[φ + 2m(β + β0)] sin[φ + 2m(β + β0)] cos Rz sin Rz ∆x sP = (43). ∆y sin[φ + 2m(β + β0)] cos[φ + 2m(β + β0)] · sin Rz cos Rz · ∆y P − − F

The negative horizontal axis implies ∆xF = 1, ∆yF = 0, so that use case is − ! ! ! ∆x cos[φ + 2m(β + β0)] sin[φ + 2m(β + β0)] cos Rz sP = − ∆y sin[φ + 2m(β + β0)] cos[φ + 2m(β + β0)] · sin Rz P − ! cos[φ + 2m(β + β0) + Rz] = − , (44) sin[φ + 2m(β + β0) + Rz] − requiring (at β = 0) tan γ0 = tan[φ + 2m(β + β0) + Rz]. (45)

This predicts ( 151.87◦,SX, φ + 2mβ0 = − (46) 22.12◦,DX. − The quality of these estimates is probably better than (41) because it was generated without intervening changes from the parallactic angle and because it was derived with well-defined centroids of the fiber plate sources instead of matching fuzzy images of celestial sources. The relevant rotation matrix in (37) defines ! 1 cos[φ + 2m(β + β0)] sin[φ + 2m(β + β0)] AT →P ; (47) ≡ s sin[φ + 2m(β + β0)] cos[φ + 2m(β + β0)] P − The inverse is (up to the scale factor) the same: ! −1 cos[φ + 2m(β + β0)] sin[φ + 2m(β + β0)] AP →T = AT →P = sP ; (48) sin[φ + 2m(β + β0)] cos[φ + 2m(β + β0)] −

The values of φ and the centers of rotation (xP c, yP c) are stored as CFG.TRANS.WCSREFANG and CFG.TRANS.BCNTR in laos.sx.hws.drot.kMirror-dev.cfg and laos.dx.hws.drot.kMirror-dev.cfg.

4.2.2 Guiding Offsets

For the guiding offsets forwarded to the IIF one needs the constants (41), (36) and the inverse of (37) to map differential motions (∆xP , ∆yP ) on the patrol camera to sky coordinates: ! ! cos a∆A ∆xP = AP →T . (49) ∆a · ∆yP LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 29

Inserting (27) into (49) we find the standard WCS matrix CDi j in the FITS headers for patrol camera images. ! ! ! ! cos δ∆α cos p sin p cos(φ + 2mβ) sin(φ + 2mβ) ∆xP = sP − ∆δ sin p cos p · sin(φ + 2mβ) cos(φ + 2mβ) · ∆yP − ! ! cos(p + φ + 2mβ) sin(p + φ + 2mβ) ∆xP = sP − − . (50) sin(p + φ + 2mβ) cos(p + φ + 2mβ) · ∆yP − The fundamental principle of operation is that the de-rotation by the K-mirrors keeps p + 2mβ time-independent to freeze both images. It suffices to obtain p and β at a single point in time of the trajectory to compute the term p + 2mβ; φ is the time-indpendent offset of (41). The software uses the simplest approach: it reads the parallactic angle p and the initial point of a new trajectory β once, at the start of the trajectory. These angles p and β are stored in the functions createTrajectory and getReady via setPangStrtAng and setMotStrtAng in laos- drot/src/Service/LaosDrotServiceWorker.cc in the properties DROT.SVC.VAR.PANG STRT ANG and DROT.SVC.VAR.MOT STRT ANG in laos.sx.hws.drot.derotation-svc.cfg and in laos.dx.hws.drot.derotation- svc.cfg . See Section 9.2 in [1] for corresponding considerations with the infrared camera.

4.3 Infrared Detector Images

4.3.1 Orientation

Relative to the upright image of a (virtual) detector at the first focal plane above the platform (after the annular mirror), an even number of reflections pushes the beam to the infrared camera:

1. DM2

2. DM3, essentially combined with DM2 a horizontal sideways motion

3. piston mirror,

4. cold M1 upwards,

5. cold hyperbolic M2 downwards (as a function of the three tilt-focus motorized degrees of freedom),

6. wheel in front of the FFTS upwards, called the dichoric mirror.11

The image is not flipped relative to the usual astrometric maps, and in consequence GEIRS does not flip the image either. See the GEIRS manual section entitled “Coordinate Systems” for a full tracing.

4.3.2 Derotation

During Com-5 it was observed that the binocular pupil image (using the pupil imager of the filter wheel on the infrared camera) turned ccw if the nominal angle of the infrared camera derotator

11effectively a metal plate as long as the fringe tracker is not in use. 30 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 increased. So effectively the camera (if looking at its surface by an observer at the dichroic) is rotating clockwise (mathematically negative) if the nominal motor angle increases. The coordinate axis attached to the detector rotates but not the beam: a passive rotation by the motor angle. To determine the value of CFG.DIRECTION in the configuration of the IR derotator, we map the sign of the derotator polynomials to motions of the infrared detector derotator by transponding the calculations of the SX GWS to the IR detector.12. The GWS SE planes are flipped but the IR images are not; this induces one sign flip of the parallactic angle: Figure3 is applicable, not Figure 11. Ifp ˙ > 0 and the IR image rotates cw in Figure3, we wish to freeze it by rotating the IR detector also cw. Combined with the sign deduced above, the nominal motor angle needs to increase. Considering in addition that the derotator polynomials have the opposite sign of the parallactic angle, Equation (63), we need to feed the IR derotator motor with the negated derotator polynomials, so CFG.DIRECTION is 1 in that case: − m = 1; IRCAM (51) −

4.3.3 WCS

GEIRS turns the IR detector image by 180◦ with the intend to deliver an image where North is up and East is to the left if the telescope points to the zenith. This is equivalent to zenith in the +y and the azimuth in the +x direction of the FITS coordinates. To determine the δ axes of the world coordinate system, we have to move the a axis cw by the parallactic angle p and cw by the motor angle βS.

To measure any offset of the motor angle βS relative to its nominal “middle” of zero degrees, 7 images of 2018-12-16 with the pupil imager were taken and angles fitted through the mid-points of the two pupils: File ARCFILE DROT POS fitted angle (deg) c7a 0039.fits ln.20181217.092111.fits 115 -13.89 c7a 0040.fits ln.20181217.092249.fits 3344 13.59 c7a 0041.fits ln.20181217.092348.fits 1729 -0.31 c7a 0042.fits ln.20181217.092451.fits 115 -13.82 c7a 0043.fits ln.20181217.092640.fits 115 -14.18 c7a 0044.fits ln.20181217.092739.fits 1729 -0.31 c7a 0045.fits ln.20181217.092852.fits 3344 13.59 A least squares fit through these 7 data pairs proposes the relation that the angle is 14.97◦ + − 0.00853◦/step, such that the estimated offset of the order of 0.03◦ is negligible. The transition from the instrument focal plane to the focal plane of the science camera rotates by the negative motor angle βS (passive rotation of the image): ! ! ∆x ∆x = A , (52) ∆y F →S ∆y S · F where ! cos( mβS) sin( mβS) AF →S =s ˆ − − − (53) sin( mβS) cos( mβS) − − 12so we have detector plane rotations, not active beam rotations. . . LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 31

converts plate scaless ˆ = 1/(sSsF ) and rotates the image by the motor angle. And setting Rz = 0 because the result should be the same for both sides by design: ! ! ∆x ∆δ = A A (54) ∆y F →S E→F cos δ∆α S · · ! ! 1 sin(p + mβS) cos(p + mβS) ∆δ = − . (55) sS cos(p + mβS) sin(p + mβS) · cos δ∆α

−5 The pixel scale is sS 0.00521 as/px 0.1447 10 deg. ≈ ≈ × By matrix inversion ! ! ! ∆δ sin(p + mβ) cos(p + mβ) ∆x = sS . (56) cos δ∆α cos(p + mβ) sin(p + mβ) · ∆y − S By exchanging the two equations (because WCS considers α the first and δ the second coordinate), equivalent to swapping the lower and upper row of the matrix, the WCS is ! ! ! cos δ∆α cos(p + mβ) sin(p + mβ) ∆x = sS − . (57) ∆δ sin(p + mβ) cos(p + mβ) ∆y · S

4.4 User Interface

4.4.1 plotSkyTrack.py

A prediction of the parallactic angle of the future is obtained by calling plotSkyTrack.py, which generates the GUI of Figure6. This GUI feeds on a regular polling of the IIF information. It predicts angles by plugging the current (α, δ)—assuming sidereal tracking—and LBT coordinates into astroplan. It is meant to give a hint of how long the derotator stages may stay tracking before hitting one of their end switches.

4.4.2 Star catalogues

4.4.2.1 Linux command line There is some auxiliary software handling local star catalogues in the format shown in http://wiki.lbto.org/bin/view/Commissioning/LBTOStarCatalogs . These ASCII files may contain comments, which means lines that start with hashes (#) or are entirely empty.13 All other lines define a list of target coordinates, one per line; they start with a name and contain information largely equivalent to the preset information: α and δ, proper motions in both (milliarcseconds per year), epoch and equinox, a magnitude in R2, star color in B R, − and the distance (arcseconds) on the sky away from the first target. These fields are separated by white space. The name of the cannot contain blanks (which are field separators) and should not contain under- scores.14 13Allowing blank lines seems to be an extension to the LBTO format, which apparently does not allow those. 14Because in a handshake between licsStarcat and the SE servers a name convention has been introduced in COM-8 where the name followed by an underscore and the magnitude is used to tag stars. This compound pseudo- name would be confusing if the star name might have underscores. . . 32 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044

Figure 6: The python program plotSkyTrack.py shows an extrapolated plot of the telescope altitude, azimuth and parallactic angle over the next 20 minutes.

The proper motion in α isα ˙ cos δ, including the same scale factor of the cosine as the star definitions in the IIF. Note that recently some files have been distributed which are erroneous and do not follow that format; they contain other color indices at places where the distance should have been stated. licsPreset sends α and δ, the proper motions, magnitudes and color indices to the telescope, presumably to apply atmospheric refraction corrections to positions (Section 5.1), see Section po- sition2 in [19]. licsPreset adds 0.5µm for the wavelengths and recomputes distances to the first star where needed, so that column of star catalogs does not need to be correct. The LN convention is that the topmost star is the target star in the field center. The guide and AO stars for patrol camera, GWS and HWS are implicitly defined by the 1 and 3 arcmin cuts in distance defined by the central hole in the annular mirror [20]. SE positions for stars farther than 1 arcmin from the target star are computed with mirror rotations, flips and plate scales for the GWS, those closer than 1 arcmin for the HWS. The magnitudes are relevant for some GWS mockup images generated by licsStarcat. If one wants to track on an (infrared) star that is invisible or absent in the (AO) star catalog, one ought to add it at the top of the file with a faint V-magnitude of (say) 22 such that it remains basically invisible in the mockup images. Note that the Telescope Pointing System uses the wavelength in the star catalog for example for dispersion corrections of the altitude; this value and proper motions should be maintained for such infrared targets in the catalog. The LN software has a program licsStarcat to deal with these files, Section 4.6. The output of the program consists of a star catalogue in the format outlined above. You can prepare star catalogues at any time far away from the telescope on any computer.

4.4.2.2 Precession Proper motions and precession from the J2000 coordinates to the equa- torial coordinates of the epoch are implemented by calling the iauAtci13 function of the SOFA library. LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 33

150 SE01 SE02 SE03 100 SE04 SE05 SE06 SE07 SE08 50 SE09 SE10 SE11 SE12 0 y [mm]

-50

-100

-150 -150 -100 -50 0 50 100 150 x [mm]

Figure 7: Assignment of Star Enlargers in the focal plane of DX GWS.

4.4.2.3 Star Enlargers A star in the field is mapped into the star enlarger’s (x, y)-plane. We first project its position s0 into the plane tangential to s at the target—where the target is placed in the center of the SE’s coordinate system:

0 fˆs = s + ∆αeα + ∆δeδ. (58)

The three factors fˆ, ∆α and ∆δ are computed by the dot products with the aid of s eα, s eδ: ⊥ ⊥ 0 0 0 fˆs s = 1; fˆs eα = ∆α; fˆs eδ = ∆δ. (59) · · · Because the angle between s and s0 is < 3 arcmin set by the outer radius of the annular mirror, the inverse of its cosine is 1/fˆ 0.9999996. ≥

4.4.2.4 Star Enlargers GWS The annular mirror flips images right-left, so the sky orien- tations relevant to the GWS are in Figure 11. Supposed the coordinate system of the SE’s is 34 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044

150 SE01 SE02 SE03 100 SE04 SE05 SE06 SE07 SE08 50 SE09 SE10 SE11 SE12 0 y [mm]

-50

-100

-150 -150 -100 -50 0 50 100 150 x [mm]

Figure 8: Assignment of Star Enlargers in the focal plane of SX GWS. There is obviously more common tilt in the associated matrices than in Figure7; tilts of that kind do not demonstrate rotations of the SE frames relative to the platform, because they are effectively recalibrated by applying the rotation offsets β0 in (61). LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 35

SE01 SE02 SE03 40 SE04 SE05 SE06 SE07 20 SE08

0 y [mm]

-20

-40

-40 -20 0 20 40 x [mm]

Figure 9: Assignment of Star Enlargers in the focal plane of DX HWS. 36 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044

SE01 SE02 SE03 40 SE04 SE05 SE06 SE07 20 SE08

0 y [mm]

-20

-40

-40 -20 0 20 40 x [mm]

Figure 10: Assignment of Star Enlargers in the focal plane of SX HWS. LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 37

−A SX +A DX

+108.5 +δ −108.5

+p +a +a

+p

+δ +A −A

Figure 11: Image orientation of a camera in the GWS focal planes. Obtained from Figure3 by a right-left flip to account for the reflection by the annular mirror. The action of the derotating motor is not yet taken into account. Because the image is flipped, the zenith direction is found by starting at δ and rotating cw through the parallactic angle p. If the time derivative of the parallactic angle isp ˙ > 0, the image rotates ccw. horizontal with +x pointing right in the image plane, and supposed the motor angles have no fur- ther offset and start at angle zero, this figure represents the frozen equatorial coordinate systems on the GWS SE’s. Taking into account the flip of the x-values (horizontal in the bench system) in Figure 11, the coordinates for the SE in the GWS are given by switching signs in the upper row of the matrix by further multiplication with ! 1 0 − . (60) 0 1

If the center of the SE (bearing) is not at the center of the beam, but has coordinates (cx, cy) in the beam system (short vector in Figure 12), one must subtract that vector to compute the position centered in the bearing system. If the GWS motor rotates ccw—viewed from the annular mirror towards the SE’s— the (x, y) image axes rotate ccw by an angle mβ + β0, such that the final image coordinates are given by a cw (or passive) rotation with the negated angles: ! ! " ! ! !# x cos[ mβ β0] sin[ mβ β0] 1 0 ∆x cx = − − − − − − y sin[ mβ β0] cos[ mβ β0] · 0 1 · ∆y − cy G − − − − F ! " ! ! !# cos[mβ + β0] sin[mβ + β0] 1 0 ∆x cx = − . (61) sin[mβ + β0] cos[mβ + β0] · 0 1 · ∆y − cy − F The sign factor m = 1 is introduced to let the angle β in the motor coordinate system be positively ± correlated with the nominal angle; m keeps track how the SE orientations are related to that internal coordinate system of the electronics, gears and switches and the sign choice of TRANS.DEGREE in the files laos.dx.gws.drot.bearing-dev.cfg and laos.sx.gws.drot.bearing-dev.cfg. β are 38 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044

platform vertical

SE vert. SE horiz

(cx,cy)

platform horiz.

Figure 12: The model of the mismatch between the center of rotation of the GWS bearing and the beam center (short arrow). The axes of the SE are rotated by an angle mβ + β0 relativ to the beam and to the horizontal platform coordinates (dashed angle). the angles shown to the observers; mβ increases if the motor turns ccw viewed from the annular mirror. The (signed) offset β0 acknowledges that for a motor at 0 steps the GWS +x axis may not be horizontal but have some inclination. The task of the derotation is to keep the positions fixed, constant in time t, as the parallactic angle changes:

◦ d φ0 + mβ + β0 = Rz p(t) + mβ(t) + β0 + 90 , (p(t) mβ(t)) = 0. (62) − dt −

(This works only if the runout (cx, cy) is zero.) This is as expected from Figure 11: ifp ˙ > 0, the image rotates ccw, and the motor must rotate GWS ccw to follow, so mβ > 0. Experience from recent experimentation is that the derotator polynomials r(t) had signs of their time derivative that had the opposite sign of the time derivative dp(t)/dt (Section 4.5.2), both for SX and for DX:

sgnp ˙(t) = sgnr ˙(t). (63) − Experience from Pathfinder (DX, see [21, p. 47]) shows that a sign flip was introduced in the LN derotator software running the motors such that the derivative of the motion in units of steps, s(t) was opposite to the derotator polynomial’s angles,

sgns ˙(t) = sgnr ˙(t), (DX) (64) − such that dp/dt and ds/dt had the same sign. [This corresponds to 1 for DROT.SVC.CFG.DIRECTION − in the configuration files laos.dx.gws.drot.derotation-svc.cfg and laos.sx.gws.drot.derotation- svc.cfg.] This is compatible with (62). By the current (irrational) sign definitions of the factors TRANS.DEGREE in the configuration files LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 39 we have for sgn s = m sgn β ( +1, GWS SX; m = (65) 1, GWS DX. − This leads to the puzzling experience that during derotations both motors will turn into the same directions, but the nomial angles in the user interface of the GWS bearing increase on one side and decrease on the other. Obviously it suffices to record the sum p(t) mβ(t) at one point in time to recover the matrix − and the positions; the derotator services do this at the start of the trajectory. An advance preview is possible that allows SE configuration even before the derotator service started if motor start positions are quasi fixed and parallactic angles are known in advance (for example by fixing the target and the start time).

4.4.2.5 Star Enlargers HWS We assume by reverse engineering that the SE of the HWS experience no flip—because the patrol camera images were measured to be flipped, Section 4.2.1, and one additional dichroic relays the beam into the AO channel. The coordinate transformation from sky positions to the SE’s two-dimensional coordinates applies scale factors of roughly 0.802 mm/arcsec.15 The 802 µm are compatible with the 96 mm of the 2 ar- cmin of [22, 10.4.2]. Both values ought be compatible with the numbers for SE.SVC.CFG.OVERLAY.FIELD - OF VIEW in laos.dx.gws.se.starEnlarger-svc.cfg. A fit to 17 measured SE positions on SX during Com-2 proposes to use values that are smaller by a factor 1.012, and this matches much better with the 601.75 scale of SX [23, p. 176] and 600.6 of DX [23, p. 178]. The transformation from patrol camera to SE units is [18, Sec. 6.5] ! ! ! x x cHx = AP →H + , (66) y y cHy H · P where the input are horizontal and vertical pixels on the patrol camera and the output microns of the FP20 image. The matrices for the two sides have units of microns per pixel: ! ! 106.131 41.487 112.474 22.77667 AP →H = , SX − , DX. (67) 41.223 105.846 22.857 112.312 − − − The two determinants are negative because the patrol camera and SE image are relatively flipped. The inverse matrices are ! ! 0.00817738 0.00320517 0.00853903 0.00173170 A−1 = , SX − , DX. (68) P →H 0.00318478 0.00819939 0.00173781 0.00855134 − − − The offset mainly indicates the translation from FITS coordinates to SE center-coordinates. ! ! ! cHx 70134 46862 = − SX, − DX. (69) cHy 24868 58402

Side note: Normalizing to unit determinant by dividing all 4 entries through the square root of the absolute value of the determinant—hence removing the scale factor of microns per pixel—the

15 613 µm have been taken from [20] for the GWS and have been scaled with the ratio of the F -fratios 20/15.28 to a HWS figure. 40 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044

AP →H matrices are ! ! 0.932859 0.364655 0.9807149 0.198601 , SX − ; DX. (70) 0.36233 0.93033 0.1993 0.9793 − − − These matrices are modelled as ! ! cos γ1 sin γ1 1 0 − (71) sin γ1 cos γ1 · 0 1 − The diagonal matrix switches the vertical component between the SE and the patrol camera, representing the dichroic that reflects the beam upwards. The arguments of the two eigenvalues of the two matrices are the rotation angles (in radians), the relative angle of rotation from patrol camera to SE coordinate systems:

( +0.372rad = 21.31◦; SX γ = (72) 1 0.200rad = 11.48◦. DX − − One would expect angles near 8.5◦ here because apparently the box with the AO cameras (and ± SE’s) is aligned with the x-y grid of the platform. Actually the numbers are different, because the cylindrical tubes of the patrol cameras and their front optics can be inserted rotated by any angle into the associated structures (not only by multiples of 90◦). Note that all these transformations do not take into account the axis runout of the K-mirrors, which is of the order of 40 pixels (6 arcseconds) in diameter on SX [18, Fig. 17].

4.4.2.6 HWS to GWS Offloading The transformation of HWS to GWS coordinates works as follows: patrol camera coordinates are derived via the inverse of (66). Instrument focal plane coordinates are from there computed with the inverse of (43), and finally GWS coordinates with (61). The parallactic angle is not needed here, but the two nominal angles and offsets of the K-mirror and GWS barrel.

4.4.2.7 Non-common Path The transformation of HWS star enlarger to infrared/science camera coordinates works as follows: patrol camera coordinates (x, y)P are derived via the inverse of (66). Instrument focal plane coordinates (x, y)F are from there computed with the inverse of (43) utilizing the constants (41), the nominal K-mirror angles β, and the signs (36). Finally science camera coordinates (x, y)S are computed with (52) using the nominal angle βS of the motor that rotates the science camera. The relation between star enlarger coordinates to CCD coordinates on the wavefront sensors is not part of this manuscript because unknown to the author. Apparently there is only one further reflection (off the pyramid) which flips along some axis depending on the way the pyramid relays the beam to the CCD, and there is the standard free parameter how the CCD surface is mounted in the mechans. The reference plate scale is 27 pixels for 2 arcmin on the sky [22, Table 13].

4.5 Notes on the IIF

The general description of the software interface is Biddick’s 481s013 [19]. LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 41

4.5.1 Wait For End-of-slewing

The end of the slewing transition after a PresetTelescope is indicated by IIFAllOnSource of the data dictionary changing to 1. The two individual IIFAzOnSource and IIFElOnSource will independently reach that state earlier.

4.5.2 Offset of the Rotator Polynomials

While slewing, the ParAngle of the data dictionary is apparently changed with the temporary pointing on sky. The angles of the GetRotatorPolynomial are those associated with the (intended, look-ahead) target position. So to correlate the rotator polynomial angles with the parallactic angle, one either needs to wait until the telescope is “on source,” or take the parallactic angle from R - TargetParAngle and L TargetParAngle of the data dictionary (with a due conversion factor of 180/π). This is demonstrated with the following table which shows data during a test run on 2017-02-02, all angles in degrees (in POSITION mode of the preset): MJD UTC ParAngle R TargetParAngle OnSource P angle 57786.74725407407 17:55:59.410 -67.775 177.150 0 354.4310 57786.75008483796 18:00:04.057 -13.883 139.645 0 248.7466 57786.75115641204 18:01:36.742 -146.999 138.788 0 248.7476 57786.75254762731 18:03:36.935 137.697 137.697 1 248.7502 57786.75476923612 18:06:48.874 135.998 135.998 1 248.7540 57786.75842708334 18:12:04.905 133.313 133.313 1 248.7594 57786.76413278935 18:20:17.815 129.393 129.393 1 248.7690 57786.76666434028 18:23:56.649 127.750 127.750 1 248.7714 57786.7683262037 18:26:20.042 126.705 126.705 1 248.7749 57786.77862875001 18:41:10.308 120.715 120.714 1 248.7857 57786.78041354167 18:43:44.444 119.758 119.757 1 248.7880 57786.78364978009 18:48:24.068 118.076 118.076 1 248.7910 57786.7851730324 18:50:35.736 99.271 73.039 0 248.8745 57786.78871634259 18:55:41.792 72.241 72.240 1 248.8725 The last column in that table shows the sum of the first (leading) coefficient of the polynomial of GetRotatorPolynomial of the right side and the value of R TargetParAngle read from the data dictionary . The top value was obtained with an incomplete preset send only to the SX and most likely refers to an older state left from a previous LUCI run. We take the sum of the parallactic angle and the rotator angle to get numbers that are (almost) constant in time; this sign combination is the effect of assigning a role of “annihilating” the effect of the parallactic angle to the rotator angles as discussed above. There is a magic offset angle between the parallactic angle of the target and the rotator polynomial of 248.8◦. (The jitter in the sum of the two angles is most likely a result of a time jitter of ≈ the order of 3 seconds between reading the data dictionary values and then obtaining first the rotator polynomials of SX and then the rotator polynomials of DX.) By which reasoning would the telescope software think that at zero parallactic angle there is an angle of 248.8◦ in the LN path? In a software test run in April 2014 this sum was 248.4◦ and 248.85◦. No such angle is mentioned in the coordinate description [13] or the wiki. The most likely explanation is that the angle is ◦ ◦ 270 τk, where τk was still configured in the PCS with the obsolete Pathfinder value of 21 as of − 42 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044

June 2017.16 This value within the PCS was corrected to 18.5◦ in Oct. 2017.17 So it is possible that the PCS sets the derotator polynomial angle at the first preset equal to the parallactic angle of the target (as if already on the sidereal track)—adjusted for the beam rotation that is basically a fixed angle proportional to how far M3 bends the beam away from the center-line between the two telescopes. 18 The derotator angles of the interface are a result of two parameters maintained inside the PCS (J. Hill, priv. commun., 2017-01-26)

LEFTZEROPOINT/RIGHTZEROPOINT to negotiate a direction of “North up” on some (represen- • tative) detector of an instrument,

LEFTSCALE/RIGHTSCALE a sign of the rotator trajectory. If set to +1 this is the same as the • LUCI direction.

We note that some technical documentation on the rotator polynomials [24] measures time in TAI MJD whereas the software interface [19] uses UTC MJD. The contemporary difference of 37 seconds in early 2017 between both time scales at the times relevant to the table and polynomial speeds less than of 0.009◦ per seconds during the hour of the measurement could account for 0.3◦ at most. We will assume that both documents are correct while the PCS well takes care of the time scales.

4.5.3 Direct Access via Python

Creation of a ICE proxy in Python that allows to send any of the telescope commands via the IIF is shown as an example in lnsw/ln/ltcs/test/iif/lbto/LbtoIifExample.py . The main steps are

to initialize ICE, • import Ice import lbto ic =Ice.initialize(sys.argv)

to get a proxy to an IIF server, • ip = ic.stringToProxy("Factory -t:default -h iif.mountain.lbto.org -p 10000")

then to connect to the server by deciding whether this should act on the left, right or both • arms of the bentGregorianBack stations

iif_sdx = iif_factory.create(’LN_IIF’,’bentGregorianBack both’,’LINC’)

define at least a pair of stars which are (formally) a guide star and a target star for the preset • start a sequence of commands • 16J. Hill, priv. commun, citing LEFTIAA and RIGHTIAA = 291, 2017-06-30 17J. Hill, priv. commun, setting LEFTIAA and RIGHTIAA = 288.5, 2017-10-10 18That would introduce the parallactic angle by queer assumptions with a wrong additive offset that does not match the sign choice of the velocities of the polynomials. LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 43

logout from the interface • ic.destroy()

A snapshot of the most important contents of the data dictionary and a coarse overview of the Rota- tor Polynomials over the next minute is obtained with lbtoSnapshot.py, see lnsw/ln/ltcs/src/iif.

4.6 Commands

The following overview of commands on the Linux shells is reproduced in a small font, because it is usually read by calling info linc from the Linux command line on a computer where the software is installed. If that command does not show a menue of the command lists, make sure that the standard search path for the info command includes $INSROOT/share/info: echo $INFOPATH This variable is usually set in $HOME/.bashrc, see Section 2.1. If someone destroyed that $INFOPATH shell variable, one may also call this with a full path: info ~/lnsw/ln/lics/doc/linc.info or with an explicit directory search path: info -d $INSROOT/share/info linc 44 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 Table of Contents

Overview ...... 1

1 AutoGuider.py...... 1 1.1 Buttons and Use...... 1 1.2 New Presets ...... 2 Linc-Nirvana Linux Command Interface 2 acquisitionCenteringSE.py ..... 2 Max-Planck Institute of Astronomy, Heidelberg 3 February 2020 3 acquisitionFindReferenceStars.py .. 3

4 acquisitionSpiralSearch.py ..... 3

5 acquisitionSpiralSearch.py ..... 3

6 cleanupConfig.py ...... 3

7 indiserver ...... 3 7.1 Compilation ...... 3 7.2 Invocation ...... 4 7.3 Implementation...... 4

8 initStages.py ...... 4

9 laos.dx.gws.drot.derotation-svr GUI.sh .. 4

10 laos.dx.gws.moe.annularMirror-svc GUI.sh .. 5

11 laos.dx.gws.moe.ccdStage-svr GUI.sh .. 5

12 laos.dx.gws.se.starEnlarger-svr GUI.sh .. 5

13 laos.dx.gws.wfc.loop-svr GUI.sh .. 5

14 laos.dx.gws.wfc.loopWFC Slopes.sh .. 5 Richard J. Mathar [email protected]

15 laos.dx.gws GUI.sh ...... 5 33 laos.sx.gws.moe.sensor-svr GUI.sh .. 7

16 laos.dx.hws.aoc.status GUI.sh .. 5 34 laos.sx.gws.se.starEnlarger-svr GUI.sh .. 7

17 laos.dx.hws.drot.derotation-svr GUI.sh .. 5 35 laos.sx.gws.wfc.loop-svr GUI.sh .. 7

18 36 laos.sx.gws.wfc.loopWFC Slopes.sh .. 7 laos.dx.hws.moe.calibrationUnits-svr GUI.sh .. 5 37 laos.sx.gws GUI.sh ...... 7 19 laos.dx.hws.moe.sensor-svr GUI.sh .. 5 38 laos.sx.hws.aoc.status GUI.sh .. 7 20 laos.dx.hws.moe.warmOptics-svr GUI.sh .. 5 39 laos.sx.hws.drot.derotation-svr GUI.sh .. 7

21 laos.dx.hws.pcam.ccd47-svr GUI.sh .. 6 40 laos.sx.hws.moe.calibrationUnits-svr GUI.sh .. 7 22 laos.dx.hws.se.starEnlarger-svr GUI.sh .. 6 41 laos.sx.hws.moe.sensor-svr GUI.sh .. 7 23 laos.dx.hws.wfc.loopCamera GUI.sh .. 6 42 24 laos.dx.hws.wfc.loopWFC Dm.sh .. 6 laos.sx.hws.moe.warmOptics-svr GUI.sh .. 7

25 laos.dx.hws.wfc.loopWFC GUI.sh .. 6 43 laos.sx.hws.pcam.ccd47-svr GUI.sh .. 7

26 laos.dx.hws.wfc.loopWFC Slopes.sh .. 6 44 laos.sx.hws.se.starEnlarger-svr GUI.sh .. 7

27 laos.dx.hws.wfc.loopXinetics GUI.sh .. 6 45 laos.sx.hws.wfc.ccd39-svr GUI.sh .. 8

28 laos.dx.hws GUI.sh ...... 6 46 laos.sx.hws.wfc.loopCamera GUI.sh .. 8

29 laos.dx.moe.hatch-svr GUI.sh .. 6 47 laos.sx.hws.wfc.loopWFC Dm.sh .. 8

30 laos.sx.gws.aoc.status GUI.sh .. 6 48 laos.sx.hws.wfc.loopWFC GUI.sh .. 8

31 laos.sx.gws.drot.derotation-svr GUI.sh .. 6 49 laos.sx.hws.wfc.loopWFC Slopes.sh .. 8

32 50 laos.sx.hws.wfc.loopXinetics GUI.sh .. 8 laos.sx.gws.moe.annularMirror-svc GUI.sh .. 6 51 laos.sx.hws GUI.sh ...... 8 52 laos.sx.moe.hatch-svr GUI.sh .. TAN8 Installation and User’s68 licsRewind.py Manual ...... 21 LN-MPIA-MAN-ICS-010 – 68.1 Command line options–...... Issue 4.04421 45 53 lbtoEquat2Horiz.py ...... 8 68.2 Rationale ...... 21 68.3 Timing ...... 22 53.1 ra/dec to alt/az ...... 8 68.4 GEIRS Interface...... 22 53.2 alt/az to ra/dec ...... 9

54 lics.drot.py ...... 9 69 licsSEOffset.py ...... 23

55 lics.dx.gws.drot.py ...... 9 70 licsSEhist.pl ...... 23

56 lics.dx.hws.drot.py ...... 9 71 licsStarcat ...... 24 71.1 Submit to Star Enlargers ...... 25 57 lics.lics.irc.drot.py ...... 9 71.1.1 Syntax ...... 25 71.1.2 Option K...... 25 71.1.3 Option f ...... 25 58 lics.sx.gws.drot.py ...... 9 71.1.4 Option t...... 26 71.1.5 Option s...... 26 59 lics.sx.hws.drot.py ...... 9 71.1.6 Option g ...... 26 71.1.7 Option G...... 26 71.1.8 Option H ...... 27 60 licsCatChk...... 10 71.1.9 Option b ...... 27 71.1.10 Algorithm HWS ...... 27 61 licsCatChk.sh ...... 10 71.1.11 Algorithm GWS ...... 28 71.1.12 Trouble Shooting ...... 28 71.2 retrieve...... 28 62 licsFmodhead...... 10 72 licsXephem ...... 28 63 licsGwsMockup ...... 11 73 liifSnapshot.py ...... 29 64 licsLogMergeAllHosts.sh .... 11 74 liifSnapshotGUI ...... 30 65 licsOffset ...... 12 65.1 Offset Telescope ...... 12 65.2 Offset Star Enlargers ...... 12 75 lircs.moe-svr GUI.sh ...... 30 65.3 United operation ...... 13 76 lnDeployAtLbt.sh ...... 30 66 licsPcam2Se ...... 14 66.1 Support HWS SE positioning ...... 14 77 lnDeployAtMpia.sh ...... 30 66.2 Support Locating Stars in PCam/Autoguider .. 15

67 licsPreset ...... 15 78 lsfits ...... 31 67.1 Preset Telescope and start tracking ..... 15 67.2 Preset derotators ...... 17 79 lsys.cab.int-svr GUI.sh ...... 31 67.3 Preset Star Enlargers to Park Positions .. 19 67.4 United operation ...... 20

80 lsys.cab.ps-svr GUI.sh...... 31

81 lsys.cryo.int-svr GUI.sh ..... 31

82 lsys.ffts.int-svr GUI.sh ...... 31

83 lsysChkNTP.sh ...... 32

84 lsysCryostatControl.py ...... 32

85 lsysWebCameraControl.py .. 32

86 ltcs.iif-svr GUI.sh...... 32

87 plotSkyTrack.py...... 32

88 setTargets.py ...... 32

89 start nirvana new...... 33

Index ...... 33 1 Chapter 2: acquisitionCenteringSE.py 2 46 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 Overview Defining the blob of the star in the image which the guider should freeze in thefocalplane is done by clicking on Select Star and then clicking in the image on the center of the star, Command interfaces to Linc-Nirvana, based on the TwiceAsNice Software of MPIA. This doc- then on Start Guiding. The auto guider in its current state locates the brightest pixel in umentation is maintained in $HeadURL: https://svn.mpia.de/gulli/TwiceAsNice/branch/unstable/ln/lics/doc/linc.texi the image as the spot that should stay at its initial position (by sending telescope offset $ . commands via the IIF). The auto-guider polls a closed-loop flag in the AO to shut itself off (meaning: not to forward 1 AutoGuider.py offsets to the telescope) once the AO has closed the loop. This is reported by one of the lines that printed by the auto guider on its standard output. If the auto-guider cannot connect to the BCU-service, it assumes that the loop is open, so it does forward offsets to AutoGuider.py -s sx -t starcat.cat the telescope. AutoGuider.py -s dx -t starcat.cat The auto guider may apparently freeze if the algorithm does not find a useful maximum in Starts the auto-guider and Patrol Camera monitor on either the SX or the DX side. Guiding its search box. The telescope offsets in alt/az that are also printed to stdout in eachloop both sides is achieved by calling the AutoGuider.py twice with two different arguments of will then be much smaller than 0.001. This happens for example if the M2 shell is ’ripped’ the side option. such that the image of the star becomes a fuzzy scattered cloud. The side can be specified with either the long option --side or with the short option -s. The button star catalogue opens a ds9 window which shows squares where the stars of the The file with the starcatalog can be specified with either the long option --targFile or star catalog are expected to appear in the image. The button does nothing if no star catalog with the short option -t. was specified at the command line. Note that this image is not updated continuously; toget the same information at a latter time you need to close the ds9 window and click again on 1.1 Buttons and Use star catalog to generate a new one. To transform this information to the SE coordinates use the licsStarcat command, See Chapter 71 [licsStarcat], page 24. To start the functionality, the usual first action is to press the Monitor button which starts reading patrol camera frames of the associated side and showing them in the main window on The button Quit terminates the auto guider, so it does no longer read patrol camera images, the right. (In Com-3 this monitoring stage was started automatically, but that automatism does no longer compute and send offsets to the telescope, and closes its windows. was removed later on the request of the PI argueing that this was not expected and that Example: the user should edit the configuration first. this is certainly an exception; the other dozen AutoGuider.py -s dx -t /data/2017-06-Com2/targetlists/bestof_starrings10mag/sr_ Linc-Nirvana services start without expecting the user to modify configuration parameters.) 17.1+05.4_0023_starrings5.cat For now, this requires that the group of IIF servers at the bottom of monit@lsys (http:// lsys.linc:2812) is running (although this should not be necessary, because reading the cameras is some internal facility that has no interface with telescope software). Depending 1.2 New Presets on the computer environment in which the command is run, the program may decide to In the current software scenario, the Autoguider is usally not stopped by anyone before run in a simulator/developer mode. In that case it prints the message someone issues a new telescope preset; it continues to submit offset commands to the tele- TaN-less mode scope. This is usually harmless, because during the initial phase of telescope slewing the to standard output when it is started. Here TaN-less means without accessing services of internal error bars within the Autoguider grow quickly out of bounds as the star disappears TwiceAsNice (TaN). from the patrol camera, and this internal check lets the Autoguider stop sending offsets. The Monitor button is labelled as Note that the Autoguider is unaware of the fact that the star catalog that has been specifi- cied on the command line becomes invalid during a new Preset. This is generally harmless, • because the Autoguider calculates the information for relative offsets and its arrrows in the Monitor patrol camera image from pointing information continuously updated by TCS queries, and if pressing it starts reading patrol camera images these will settle to the correct values at the end of slewing. [Currently the Autoguider does not try to draw stars of the star catalog into any of its maps. If it ever does, it ought • Stop Mon compare the mid-point of the online pointing with the coordinates of the target in its star catalog to detect whether its star catalog has become invalid.] if pressing it stops reading patrol camera images Pressing the AutoGuide button enters a mode of guiding (sending offsets/corrections to the telescope) by analyzing the patrol camera images. The button can only be pressed if the 2 acquisitionCenteringSE.py Monitor is active (because otherwise there would be no new images to analyze).

3 Chapter 9: laos.dx.gws.drot.derotation-svr GUI.sh 4

3 acquisitionFindReferenceStars.py This will create $INSROOT/bin/indi_linc_lircs. Note that the source code tries to figure out whether the indiserver has been compiled; if this was not the case,no valid indi_linc_lircs file will be created and the indiserver will die after some failed 4 acquisitionSpiralSearch.py attempts to connect to that "device". The standard use case on the jenkins test installation is that the 3rdparty directory is not compiled, so neither the indiserver nor the LINC-NIRVANA device are compiled. For that reason, unit test scenarios for the server should not be called by default from 5 acquisitionSpiralSearch.py the automake tools.

Print the time right now in the local timezone of Phoenix/Arizona. This is mainly a shortcut 7.2 Invocation for people working in Germany or on computers with a UTC default time zone. The indiserver is started on lircs.linc with indiserver $INSROOT/bin/indi_linc_lircs & 6 cleanupConfig.py and can be tested then with indi_getprop

7 indiserver 7.3 Implementation syntax: indiserver $INSROOT/bin/indi_linc_lircs The LINC-NIRVANA INDI device responds to "get property" queries of some client (which supposedly is the FACSUM) by looking at the properties and values found in the The indiserver is compiled and started on the lircs.linc computer to respond to property $CAMTMP/geirsPhduAdd.nirvana_2 file, located in the GEIRS directories. (For that reason queries from the FACSUM (facility summary) clients with the aim to monitor LINC specific it is futile to call the indiserver on another computer, because GEIRS is only compiled and parameters that may be useful for LBTO handling. In particular the temperature and living on lircs.linc.lbto.org) . That file is populated by the lircs.fits-svr which assembles pressure parameters of LINC-NIRVANA are of interest in emergency power supply cases. some of the LINC-NIRVANA property values. So the set of properties that are reported by the INDI server is not configured in some extra files, but is just a rephrased setofthe 7.1 Compilation very same set of values that are assembled for the header keywords of the infrared detector The compilation within LINC-NIRVANA consists of two parts: FITS files. compilation of the standard indiserver binary into $INSROOT. This happens by by The LINC-NIRVANA INDI device does not report any values that are assembled from • compiling the libnova library and then compiling the indiserver. The standard steps the iif-svr, which reflects the telescope status. (That would be futile, because FACSUM is are already aware of these). As implemented, the LINC-NIRVANA INDI device contains no de- tector specific properties, because geirsPhduAdd.nirvana_2 contains only complementary cd ~/lnsw/ln/3rdparty instrument parameters that are not known to GEIRS. autoreconf -i -s ./configure --prefix=$INSROOT 8 initStages.py make install This is to be done because the 3rdparty subdirectory of the source code is usually not included into the auto-tools of the standard make. 9 laos.dx.gws.drot.derotation-svr GUI.sh This compilation will skip a lot of the default indiserver installation because the LINC- NIRVANA case does nto support to configure or initiate devices through the indiserver syntax: laos.dx.gws.drot.derotation-svr_GUI.sh but only passive queries of some parts of the property trees. Control (start, stop,...) the derotation motor for the GWS on the DX side. Note that The libnova indiserver libraries and headers end up in $INSROOT/lib, the GUI will not show the buttons and fields unless the associated service has been started $INSROOT/include and so on. for example with monit or with rcbasdard.sh start laos.dx.gws.drot.derotation-svr compilation of a device "LINC". • --CONFIG=laos/dx/gws/drot/laos.dx.gws.drot.derotation-svr.cfg cd ~/lnsw/ln/lircs The colors used in the derotator GUIs are misleading. They show green arrows, when the make install derotator is stopped, and red rockets when the derotators are running. This is about the 5 6 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 47 opposite of a good human-machine interface, where the red colors should be reserved for 21 laos.dx.hws.pcam.ccd47-svr GUI.sh erroneous states and the green colors for the good working states.

10 laos.dx.gws.moe.annularMirror-svc GUI.sh 22 laos.dx.hws.se.starEnlarger-svr GUI.sh

11 laos.dx.gws.moe.ccdStage-svr GUI.sh 23 laos.dx.hws.wfc.loopCamera GUI.sh

12 laos.dx.gws.se.starEnlarger-svr GUI.sh 24 laos.dx.hws.wfc.loopWFC Dm.sh

13 laos.dx.gws.wfc.loop-svr GUI.sh 25 laos.dx.hws.wfc.loopWFC GUI.sh

14 laos.dx.gws.wfc.loopWFC Slopes.sh 26 laos.dx.hws.wfc.loopWFC Slopes.sh

15 laos.dx.gws GUI.sh 27 laos.dx.hws.wfc.loopXinetics GUI.sh

16 laos.dx.hws.aoc.status GUI.sh 28 laos.dx.hws GUI.sh

17 laos.dx.hws.drot.derotation-svr GUI.sh 29 laos.dx.moe.hatch-svr GUI.sh syntax: laos.dx.hws.drot.derotation-svr_GUI.sh Control (start, stop,...) the derotation (K-mirror) motor for the HWS on the DX side. Note that the GUI will not show the buttons and 30 laos.sx.gws.aoc.status GUI.sh fields unless the associated service has been started for example with monit or with rcbasdard.sh start laos.dx.hws.drot.derotation-svr --CONFIG=laos/dx/hws/drot/laos.dx.hws.drot.derotation-svr.cfg 31 laos.sx.gws.drot.derotation-svr GUI.sh

18 laos.dx.hws.moe.calibrationUnits-svr GUI.sh syntax: laos.sx.gws.drot.derotation-svr_GUI.sh Control (start, stop,...) the derotation motor for the GWS on the SX side. Note that the GUI will not show the buttons and fields unless the associated service has been started 19 laos.dx.hws.moe.sensor-svr GUI.sh for example with monit or with rcbasdard.sh start laos.sx.gws.drot.derotation-svr --CONFIG=laos/sx/gws/drot/laos.sx.gws.drot.derotation-svr.cfg

20 laos.dx.hws.moe.warmOptics-svr GUI.sh 32 laos.sx.gws.moe.annularMirror-svc GUI.sh

7 8

33 laos.sx.gws.moe.sensor-svr GUI.sh 45 laos.sx.hws.wfc.ccd39-svr GUI.sh

34 laos.sx.gws.se.starEnlarger-svr GUI.sh 46 laos.sx.hws.wfc.loopCamera GUI.sh

35 laos.sx.gws.wfc.loop-svr GUI.sh 47 laos.sx.hws.wfc.loopWFC Dm.sh

36 laos.sx.gws.wfc.loopWFC Slopes.sh 48 laos.sx.hws.wfc.loopWFC GUI.sh

37 laos.sx.gws GUI.sh 49 laos.sx.hws.wfc.loopWFC Slopes.sh

38 laos.sx.hws.aoc.status GUI.sh 50 laos.sx.hws.wfc.loopXinetics GUI.sh

39 laos.sx.hws.drot.derotation-svr GUI.sh 51 laos.sx.hws GUI.sh syntax: laos.sx.hws.drot.derotation-svr_GUI.sh Control (start, stop,...) the derotation (K-mirror) motor for the HWS on the SX side. Note that the GUI will not show the buttons and fields unless the associated service has been 52 laos.sx.moe.hatch-svr GUI.sh started with monit or with rcbasdard.sh start laos.sx.hws.drot.derotation-svr --CONFIG=laos/sx/hws/drot/laos.sx.hws.drot.derotation-svr.cfg 53 lbtoEquat2Horiz.py 40 laos.sx.hws.moe.calibrationUnits-svr GUI.sh The python script lbtoEquat2Horiz.py converts horizontal coordinates (altitude and az- imuth) to equatorial coordinates (right anscension and declination) and vice versa. The transformation is correct at time ’now’ when the script is executed and for the LBTO geo- 41 laos.sx.hws.moe.sensor-svr GUI.sh graphic coordinates. This is meant to give a quick idea of how close the target may be to the horizon. The azimuth convention is N=0, E=+90 as elsewhere in the software. The functionality does 42 laos.sx.hws.moe.warmOptics-svr GUI.sh not depend on or connect to the IIF. 53.1 ra/dec to alt/az 43 laos.sx.hws.pcam.ccd47-svr GUI.sh The transformation from equatorial to horizontal is done with lbtoEquat2Horiz.py ra/degrees dec/degrees lbtoEquat2Horiz.py hh:mm:ss +-dd:mm:ss 44 laos.sx.hws.se.starEnlarger-svr GUI.sh where right ascension and declination are either provided in degrees or in the hex-decimal hour and degrees format. Chapter 59: lics.sx.hws.drot.py 9 10 48 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 53.2 alt/az to ra/dec 60 licsCatChk The reverse transformation from horizontal to equatorial is done by adding the option -r lbtoEquat2Horiz.py -r alt/degrees az/degrees licsCatChk [-v] catfile.cat [ catfile2.cat...] lbtoEquat2Horiz.py -r dd:mm:ss +-dd:mm:ss All Linc-Nirvana star catalog files on the command line are checked for common errors, including integer and floating point formats in the RA/DEC coordinates, proper motions where altitude and azimuth angle either provided in degrees or in the hex-decimal degrees and magnitudes. Errors are printed if the hour value of the RA coordinate is not an integer format. in the range 0 to 24, if the degree value of the DEC coordinate is missing a sign or not an integer in the range -90 to +90, if the minutes of the two coordinates are not unsigned 54 lics.drot.py numbers in the range 0 to 60, if the seconds in the two coordinates are not positive floating point numbers in the range 0 to 60, if the two equinox fields do not refer to J2000, ifthe proper motions are not floating point numbers. lics.drot.py The option -v (verbose) triggers that for each file of the command line one line is echoed, Starts derotation on all 5 derotation motors (sx/dx, gws/hws, and infrared detector) at even if the catalog file passes all these tests. If the option is not used, only erroneous files their current positions. are reported.

55 lics.dx.gws.drot.py 61 licsCatChk.sh lics.dx.gws.drot.py licsCatChk.sh [-v][-p][catdir1 catdir2...] Starts derotation on the DX GWS bearing at its current position. The Linc-Nirvana star catalog files in the directories listed on the command line are indi- vidually checked for syntax errors with licsCatChk See Chapter 60 [licsCatChk], page 10. 56 lics.dx.hws.drot.py The script actually assumes every file with the suffix cat is a catalog file to be tested. This is a convenient wrapper for the licsCatChk which only checks files but not entire directories, and which does not modify files. lics.dx.hws.drot.py The option -v can be used for more verbose output: each file with the suffix cat is echoed Starts derotation on the DX HWS K-mirror at its current position. on output, not only those with errors. This gives an feedback on which files have actually be checked. 57 lics.lics.irc.drot.py The option -p is used to patch these catalog files for the most common error that isfre- quently found in catalog files of the LN commissioning: it triggers that every substring nan is substituted in place by the string 0.0 in every catalog file. lics.irc.drot.py If there are no directories or files names on the command line, the current working directory Starts derotation of the motor of the infrared/science detector. is scanned for catalog files. Example: 58 lics.sx.gws.drot.py cd /data/2019-10-Com9 licsCatChk.sh -v targets targets2 lics.sx.gws.drot.py Starts derotation on the SX GWS bearing at its current position. 62 licsFmodhead

59 lics.sx.hws.drot.py licsFmodhead fitsfile.fits tplhdrfile1.tpl [ tplhdrfile2.tpl...] The file fitsfile.fits is changed by adding the template header lines in tplhdrfile1.tpl lics.sx.hws.drot.py and further optional files into the primary header. Starts derotation on the SX HWS K-mirror at its current position. For the valid syntax of template header files consult the cfitsio programmer’s manual.

11 12

63 licsGwsMockup 65 licsOffset

The command moves the telescope and/or a subset of star enlarger arms at the same time licsGwsMockup -s {sx|dx} lbtocatfile defined by a stroke and direction in the equatorial system (in sky coordinates). The program generates a fake image of a virtual camera in the GWS focal plane of the SX or the DX side (exactly one of which must be selected by the -s switch) by rendering 65.1 Offset Telescope the catalog file (last command line parameter) with sky, the simulator of the skymaker licsOffset -t -O raoffsetarcsec decoffsetarcsec tools. A temporary FITS file is created and shown with ds9 with a 6x6 arcmin field of licsOffset -t -S server -O raoffsetarcsec decoffsetarcsec view. If sky or ds9 have not been found at compile time, the command does nothing. If the switch -t is used, this sends two differental pointing offsets to the telescope, an offset Consult the section concerning installation in LN-MPIA-MAN-ICS-010 (https://svn. in right ascension and an offset in declination. The offset in RA is not the bare offsetin mpia.de/trac/gulli/ln/archive/Archive/LN%20Documentation/Manuals%20(MAN)/ the right ascension, but it includes the cosine of the declination (as usual for proper motion Instrument%20Control%20Software%20(ICS)/LN-MPIA-MAN-ICS-010.pdf) if needed. cataloges or the PCA GUI of the LN operator, for example.) This means to move along The 1 and 3 arcmin radii indicating the subselection by the annular mirror are marked as the 45 degrees diagonal in the alpha/delta system, the two values need to be the same. two white circles in the image. Each star in the catalog is surrounded by a small square Both arguments are given in arcseconds, and must be present after the -O switch (dash such that all of them can be spotted even if the differences in their magnitudes are large. capital-O). This means, not to change one of the RA or DEC coordinates a zero must be The labels at the squares are the target names in the left-most fields of the star catalog. placed. There is a restriction on the throw (square root of the sum of the squares of the two offsets) by the copointing limit of the two telescop arms; licsOffset does not check Two WCS coordinate systems are compiled into the FITS header: such a constraint, but the telescope interface may reject offsets for that reason. the usual equatorial system in RA and DEC with grid lines drawn across the image. To • If the option -S is not used, the server defaults to ltcs.iif-svr, which is the standard get rid of these lines, use the Analysis->Coordinate Grid menue. Note that this is the setup of operating the telescope on the mountain. Otherwise one may use -S equatorial system precessed to the current time of the observation; so the coordinates ltcs.iifDummyLocalhost-svr for debugging, supposing that service has been started. will differ from the input coordinates and the RA/DEC coordinates ofthe TCS, which refer to the equator of 2000. 65.2 Offset Star Enlargers the WCSA system with the linear scale of the focal plane coordinates relevant to the licsOffset [-v] -s all -O raoffsetarcsec decoffsetarcsec • F system of the star enlargers, where (0,0) is in the middle and the range along x and y is +-120 thousand. The actual coordinates are updated in the WCS a menue as long licsOffset [-v] -s sx -O raoffsetarcsec decoffsetarcsec as the cursor is in the main window. licsOffset [-v] -s dx -O raoffsetarcsec decoffsetarcsec licsOffset [-v] -s dx.gws -O raoffsetarcsec decoffsetarcsec licsOffset [-v] -s Stars are simulated with one arcsecond of seeing, with an integration time inversely propor- laos.dx.gws.se.starEnlarger-svr -O raoffsetarcsec decoffsetarcsec tional to the flux of the brightest star, and assuming a background of 22 mag perarcsecond licsOffset [-v] -s sx.gws -O raoffsetarcsec decoffsetarcsec licsOffset [-v] -s squared, 2 ADU read noise, and an overall quantum efficiency (detector efficiency multiplied laos.sx.gws.se.starEnlarger-svr -O raoffsetarcsec decoffsetarcsec by telescope transmission) of 0.6. licsOffset [-v] -s dx.hws -O raoffsetarcsec decoffsetarcsec licsOffset [-v] -s The images are flipped and rotated such that the x axis ofthe SE focal plane is horizontal laos.dx.hws.se.starEnlarger-svr -O raoffsetarcsec decoffsetarcsec in the image. licsOffset [-v] -s sx.hws -O raoffsetarcsec decoffsetarcsec licsOffset [-v] -s laos.sx.hws.se.starEnlarger-svr -O raoffsetarcsec decoffsetarcsec If the switch -s is used, the command moves the two star enlargers of one side or one 64 licsLogMergeAllHosts.sh individual star enlarger set assuming offsets in right ascension and declination. The string after the -s defines a subset of 1, 2 or 4 of the set of4 SE subsystems that Linc-Nirvana has. The 4 SE sets are characterized by combining sx or dx with gws or hws. The string This shell script gathers the log-file lines on the level of INFO on the LN hosts (laos, laos2, all means we want to move all 4 SE subsystems; the string sx or dx means we want to lircs,...), sorts them according to date and time, eliminates the coloring, and copies the move only the 2 SE substems belonging to one of the two LBT arms, and the other allowable merged file into $INSROOT/var/log of the local host. strings are selecting a base name of one of the configuration files in lnsw/config. Assuming that all services use a well coordinated level of logging, which puts the information The option -O (capital-O, meaning offset) must be present and followed by two numerical of permanent interest in the I LOG macros and all information of lower valency into the arguments in units of arcseconds. The numerical differential right ascension must include N LOG and higher levels, the combined file is a suitable night log summary. the cosine of the declination in the same sense as defined in the interface with the -t option. Chapter 65: licsOffset 13 14 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 49 Note that the signs here in the SE directions are consistent with the use in the telescope 66 licsPcam2Se offsets, which means that positive RA or DEC let the SE actually move in the negative direction (in their rotated local coordinate systems) to compensate for the associated shift of the image plane, with the proposition to stay locked on their target stars even if the telescope moves. (In a perfect world with instanteneous effects without delays and precise 66.1 Support HWS SE positioning SE positioning, that action would allow keeping the AO loop closed while dithering or taking licsPcam2Se -s {sx|dx} [-b] flat fields on the infrared detector.) So the expected invocation isthatthe -t and the -s are used at the same time with a single pair of offsets. The program retreives a patrol camera image, analyses which stars are in it, converts the pixel positions to the focal plane coordinates of the HWS SE on the associated side, and The option -v lets the program print the computed offsets in units of microns in the asso- tries to figure out a set of non-colliding SE arms to reach these positions, and eventually to ciated SE focal plane to stdout. move these SE arms. One difference to the licsStarcat Chapter 71 [licsStarcat], page 24, command is that The option -s selects either the SX or the DX side of the telescope. licsStarcat just proposes target coordinates in the SE GUI’s, whereas licsOffset tries to move them without waiting for human intervention. (Of course that may fail for all The steps are standard reasons like SE arm collisions...) 1. get a single picture of the patrol camera on one side. Which side is configured by the The software tries to move all (enabled) star enlargers that are in the infield of the circular command line option. radius of 1 or 3 arcseconds; it does not know whether SEs in these annular rings are 2. Run sex on that image. Eliminate stars that are outside the 1 arcmin radius (because associated with some stars or just hang around there because the operator was too lazy to the patrol camera has a slightly larger FOV). Order the output by star brightness move them out of the field. It is recommended to park all SEs that are not in use outside this (priority) according to the sex pseudo-magnitude. Return these as a SeqPoint with perimeter of 1 or 3 arcminutes to let the software know that these should not be moved by units of pixels. the command. (This is usually achieved by using the -s of Chapter 67 [licsPreset], page 15, 3. Map this list to SE coordinates (with one of Kalyan’s matrices of 2017-03, depending or pressing the Park button in the SE GUI.) Obviously that is not strictly necessary for the on side) which again is a SeqPoint SEs that contribute with negligible flux to their cameras. 4. construct an association with SE arms (1-8) with the associated Starcat library function, There is currently no incremental implementation that checks whether some of the SE’s and call licsSEPreset.py to display in the SE GUI the proposed position of the SE exceed their motion range if their initial position is close to the boundaries of their travel arms. ranges and if the throw is large. In practise, if any one of the SE’s of one SE set would have to move out of its travel range or collide with another arm, no one will actually move The program shows the current Patrol Camera image flipped and rotated in a ds9 GUI with because there is a standard validation step in the SE motor’s to inhibit such attempt of a superimposed coordinate system of the SE plane (in units of microns). This GUI can be a parallel move. Example: if the SE02, SE05 and SE08 of the SX GWS need to move by prevented with the -b option. -424,-2517 and the SE04 and SE07 of SX HWS by 1115,-3148 at the same time, and if SE05 cannot move that far because it is already too close to one of its limits, SE02, SE05 and If you wish to click on a star in that ds9 image and to freeze the associated pair of (x,y) SE08 of SX GWS will not move, but only SE04 and SE07 of SX HWS. In such cases of coordinates to copy the numbers into the SE GUI, select Edit->Crosshair in the ds9 menu large offsets, the operator would actually need to run a new SE acquisition to assignthe and click on the star’s position in the image. Then the ds9 GUI does not change the stars to a different set of SE arms. coordinates when the mouse cursor leaves that GUI. The program is usually called indirectly from within licsStarcat See Chapter 71 [licsStar- 65.3 United operation cat], page 24. The command line options -t, -s are commonly combined. See for example The program is not available (which means: it does nothing) if the executable sex of the sextractor was not found at compile time. licsOffset -t -s all -O 5 5 licsOffset -t -s dx -O 0.0 -3.3 In Nov. 2017 it was found that licsOffset -t -s all -O 2.2 2.2 1. the collision detection in the motor library is not safe enough to avoid collisions; licsOffset -s sx -O 0.0 1.5 2. the localization of the stars in saturated images is not faithful with the current imple- The command uses the same library as licsStarcat Chapter 71 [licsStarcat], page 24, mentation; and licsPreset Chapter 67 [licsPreset], page 15, to compute the image transformations. The offsets for the star enlargers are forwarded to licsSEOffset.py Chapter 69 [licsSE- so the line in the licsSEPreset.py that would actually try to move the SE’s has been Offset.py], page .23 commented.

Chapter 67: licsPreset 15 Chapter 67: licsPreset 16

66.2 Support Locating Stars in PCam/Autoguider The LINC proxy server will use the subset of common sides as the active setup. Problems occur if licsPcam2Se -s {sx|dx} -G Kmirr/deg -p parall/deg ra/degrees dec/degress starcatfile.cat The TO has authorized LINC on the opposite side of the LINC configuration or on • none. This effectively disables the commands PresetTelescope, OffsetGuiding and If the program is called with three trailing parameters (as shown) it displays the Patrol OffsetPointing and GetRotatorPolynomials and reduces the instrument to reading Camera image of that side with ds9, assumes that the data dictionary items. 1. the current K-mirror angle (in degrees) is as given in the -G, This does not yet work for the OffsetPointing2 command that may be started from • 2. that the current parallactic angle (in degrees) is as given in the option -p, and that the within the AutoGuider: the IIF proxy server will terminate if the TO’s authorization final three arguments are differs from the LINC configuration. The configurations must agree to be either both 3. the current right ascension in degrees arms or the same arm of the telescope. 4. the current declination in degrees Note that this does not contact the telescope TCS server directly but forwards the command 5. the star catalog file in the LBTO format for the current pointing. to the Linc-Nirvana proxy implied by the -S option, so this server needs to be running to It shows the Patrol Camera image (frozen, at the time of the call) as is, which means have any effect. This is the same server that is used to request the derotator polynomials showing the sky flipped and rotated in the same orientation as the AutoGuider shouldsee from the TCS. So the server will be already running if any of the 5 derotator services is it. The usual Ra/Dec grid is shown by default (and can be manipulated with the usual ds9 running. If a message of the style Exception: Failed connecting to ... iifDummyLocalhost.. buttons), and the predicted position of each star of the star catalog is marked by a yellow appears, the service is not running. The usual way of achieving this is to run a browser on square. The label at the yellow square is taken from the first field of each star in the star http://lsys.linc:2812 and to enable the iif monit services on the bottom of the page. catalog file. If the program returns almost immediately after just echoing the number of stars in the catalog and the position of the main target, without any further effect, the LN proxy server The main use of that variant is a call via the button in the AutoGuider (which fills in all may not be running (and the preset never reach the telescope). the online arguments). The ds9 GUI should be closed if the information is not needed. If the option -S is not used, the server defaults to ltcs.iif-svr, which is the standard setup of operating the telescope on the mountain. Otherwise one may use -S 67 licsPreset ltcs.iifDummyLocalhost-svr for debugging (if that service has been started). If the option -b is used, the program runs in a batch mode and does not pop-up the GUI’s mentioned further down. This option is permanently activated due to a request of a system 67.1 Preset Telescope and start tracking engineer after Com-3, so use or omission on the command line does not have an effect now. licsPreset -t [-b] starcat.cat As a feedback the command shows the number of stars in the catalog, the coordinates of licsPreset -t [-b] -S server starcat.cat the central target, the parallactic angle and its time derivative, and the current position of the target in Alt/Az coordinates. (The time derivative of the parallactic angle indicates This sends a preset to the telescope given the file name with the star catalog as the final which directions the derotators need to move to freeze the rotating images. The motor command line argument. speed in units of steps over time will need the same sign for all 5 derotators. The motor The starcat.cat file must be available on the local file system of the computer wherethe speed in units of nominal degrees over time will need the opposite sign for one of the GWS command is started. Usually that would be a file in the /data disk which is cross-mounted derotators.) from litter.linc. If Note that the telescope refuses to acquire a target too close to or below the horizon. The cd /data ; ls Telescope Operator or the Error messages in the TCS simulator will reveal the reasons for reveals that the contents is not yet mounted, use cat /etc/fsdisk ; mount -a as super such a failure, and of course the value of the altitude printed by the command will be user to mount it, or use licsPreset on ln-x1 where this is usually the case. negative then. The telescope operator should have authorized The preset will pop up a AladinLite window centered at the target coordinate with a FOV LINC of approximately 6 arcmin. This may be used as a visual check that you picked the star catalog in the command line that was intended. The preset will also pop up a Chapter 74 on the same arms (left, right or both) of the telescope as configured in the [liifSnapshotGUI], page 30. These two auxiliary GUI’s may be closed without any further lnsw/config/ltcs/*-dev.cfg of the Linc-Nirvana proxy server through the FO- side effects to save screen space, or be prevented with the -b option. CAL STATION and COMMAND SIDE properties. Since Jan 2018 this is no longer strictly required. The Telescope Operator may authorize LINC on both sides or only one, The program returns to the Linux shell if and the configuration in the LINC files may at the same time be either both or one side. the telescope has settled into the tracking mode, • Chapter 67: licsPreset 17 Chapter 67: licsPreset 18 50 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 the command failed for some reason, converts motor steps to degrees. So the travel ranges should not be surrealistic wide open • the telescope needed longer than the IIF timeout value (4.5 minutees) to acquire the intervals with a hidden agenda to move the motor arbitrarily into the limit switches in • target. some testing cases, but close to or slightly narrower than the actual design of the hardware. A starting position is selected which stays at least the backlash distance away from these 67.2 Preset derotators (software) limits. So the file starcat.cat should contain a target that will be used in the telescope pointing, licsPreset -d all [-D offsetDegrees] starcat.cat either the one on which the telescope is currently tracking or the one that is preset with licsPreset -d sx [-D offsetDegrees] starcat.cat the same licsPreset. licsPreset -d dx [-D offsetDegrees] starcat.cat Note that the preset first moves the motor(s) to the(ir) start position at their high cruis- licsPreset -d laos.dx.gws.drot.derotation-svr [-D offsetDegrees] starcat.cat ing speed. (This is a fundamental difference to the lics.drot.py and similar commands which start the derotation at whatever the current positions are.) During that stage the licsPreset -d laos.sx.gws.drot.derotation-svr [-D offsetDegrees] starcat.cat laos.xx.xxx.drot GUI’s show a status of Moving Absolute, and the background color is licsPreset -d laos.dx.hws.drot.derotation-svr [-D offsetDegrees] starcat.cat yellow. licsPreset -d laos.sx.hws.drot.derotation-svr [-D offsetDegrees] starcat.cat The start position is calculated by putting as much time as possible, with a max- licsPreset -d lircs.moe.drot-svr [-D offsetDegrees] starcat.cat imum set by the product of DROT.SVC.CFG.NUMBER OF POLYNOMIALS and Moves all 5, 3 of the 5, or one individual derotator motors to the start position. The option DROT.SVC.CFG.SAMPLING RATE, into the derotation trajectory. This time is reduced -d followed either by all or by sx or by dx or by a single name of a derotation server if needed, if the travel range of the motor would not cover that full angle; this typically moves all five services in parallel or the one addressed by the configuration filenametoa happens at large speeds of the parallactic angle. Here it may become essential that the position preferred for starting the derotation. Note that the auxiliary parameter after the MOD.X.CFG.DATASHEET.TRAVELRANGE and the CFG.TRANS.DEGREE properties -d is mandatory; you cannot write the file name starcat.cat right after the -d. The options of the derotation motor are not specifying a lower or upper limit that is outside the sx or dx start derotation of the HWS and GWS derotators on their side and also rotation motor’s actual limits. This mapping of the track of the derotator polynomials to the of the infrared detector, as if the infrared detector were a common element of both sides. motor range is done individually for the up to five derotators. Usually the travel range of the infrared detector’s derotator is the smallest of them (30 degrees in total), so often the The cases -d all, -d sx and -d dx spawn subprocesses which execute indivdually; even if derotators of the GWS and HWS beams will continue their derotation while the infrared one of the derotators runs into problems (because motors or services other interfaces fail), detector’s derotation has already stopped. [Re-winding and restarting derotations is the others will continue their mission. The obvious reason for that lenient behavior is that not done automatically. The operator must monitor the status and may decide to use integration into an automated system can use a fixed syntax -d all because the subsystems licsPreset to restart the IRC derotation and let the others continue not to loose the figure out by themselves whether they are currently active/cooperative ornot. associated SE positions.] The -D offsetDegrees may be used to adjust the motor start angle computed by the Realizing that not many people know how to start the virtual machine simulator of the algorithm detailed below by as many degrees as specified by the signed offsetDegrees. telescope subsystem, the IIF proxy server creates rotator polynomials even if the TO has If more than one derotator is addressed by the command, all of these derotators get the not authorized the instrument. If the proxy server realizes that the instrument is not same offset. Note that the effect on the beams that run through the K-mirrors is twicethat authorized at all or not authorized at the side it is active, the proxy server does not ask value. If the option is not used, the offset angle is zero. If application of that differential the telescope interface for the polynomials but creates them itself, based on the current angle would lead to a start angle outside the limits of the motor, the value is reduced (in pointing coordinates, the geographic position on the mountain and the implementation of absoluted value) to keep the start angle in the limits. Nonzero angles will generally shorten the SOFA library. So for tests of the functionality of the derotators on the mountain during the maximum derotation time. The most important side effect of this option is that this bad weather conditions of when another instrument is operative, the derotator trajectories implicitly also rotates matching positions of the star enlargers by the same angle (or twice will still be reasonable. There is a small disadvantage here, because the derotators may that angle after K-mirrors). deceive the instrument operation, behaving rationally even if the TO did not authorize the That position is configured by the star catalog which is specified by the file name attheend instrument. That risk seems to be small, because a telescope preset will fail vividly in these of the command. The first star in the star catalog defines a position on the sky andthat cases, causing a sufficently high level of alarm to the instrument operator. implies a trajectory of the parallactic angle in the forseable future. A position is chosen The two derotators for SX and the two derotators for DX request the sided derotator that lets this trajectory fit into the free travel range of the motor (once the derotation will polynomials from the TCS. The derotator of the infrared detector is fed with the polynomial actually start). If the configured desired duration of the trajectory is larger than thetravel of the active side in monocular mode, and with the arithmetic mean of the two polynomials range, the duration will be shortened until it fits. in binocular mode. As noted above, binocular mode means that the TO has authorized Note that this command uses the parameters of the configuration files for the five derota- the instrument on both sides and that the BASDA configuration file of the iif server uses tor motors, in particular the travel ranges, backlash, and the transformation matrix that “bentGregorianBack both” for the FOCAL STATION.

Chapter 67: licsPreset 19 Chapter 67: licsPreset 20

During that stage the laos.xx.xxx.drot GUI’s show a status of Start External Profile..., The obvious reason for that lenient behavior is that integration into an automated system and a field labeled PA shows the parallactic angle at the time when derotation started. The can use a fixed syntax -s all because the subsystems figure out by themselves whether background color is green then. Note that these parallactic angles of the various derotators they are currently active/cooperating or not. differ, because the motors start independently and asynchronously at different times. The park position is defined by setting the motor along the y to the zero (home) position To start the derotators the associated motors must have been powered on (use (which is also the negative limit) and the motor along the x coordinate to the middle of its lsys.cab.ps-svr_GUI.sh if in doubt) and the associated servers must have been started, travel range. http://laos2.linc:2812. This preset of the star enlargers prepares for motions to be triggered by licsStarcat (once The computer on which licsPreset is run and the server where the deroator services are the derotators have started). The rationale is to move all star enlargers as far as possible run must have sufficiently close clocks on the operating system (usually achieved by running out of the common field as to minimize the probability of collisions for (yet unknown) star NTP servers on both), because desired start times are computed on absolute time scales enlarger motions to come. on the licsPreset-client and forwarded as such to the server, which refuses to start motors In addition, moving the star enlargers to these positions before switching power off mini- if the trajectories start in the past or in a too-close future. mizes the risk that during the home search of the next startup star enlarger 11 of the two If the -d is used and also -s, a call of Chapter 71 [licsStarcat], page 24, is issued once the GWS stages may run into one of its neighbours. This may happen if the backslash removal derotation started. The obvious benefits are stride of SE 11 is larger than the distances of the neighbours from the SE home position. that the operator does not need to call licsStarcat separately, • that the timing is optimized, 67.4 United operation • and that the star catalog file name needs to be known only at one place. • The command line options -d, -t, -s can be mixed (combined). The syntax is If the -d all is used but one side of the telescope is not authorized for Linc-Nirvana, licsPreset [-t] [-b] [-S server][-s {all|sx|dx|laos.sx.gws.se.starEnlarger- harmless errors of the form Error while asking for rotator polynomials are printed for svr|...}][-d {all|sx|dx|laos.dx.gws.drot.derotation-svr|...}][-D that non-authorized side, once for HWS and once for GWS. (The TCS server does not drooffsangle] starcat.cat produce rotator polynomials for non-authorized sides.) Examples: licsPreset Note that presetting and starting the derotators with still al- licsPreset -t -d all -s all $INSROOT/etc/starcat.cat lows the operator to stop, reposition and restart derotatiors via the derotator licsPreset -t -d all $INSROOT/etc/starcat.cat GUI’s at any time, See Chapter 39 [laos.sx.hws.drot.derotation-svr GUI.sh], licsPreset -d sx -s sx $INSROOT/etc/starcat.cat page 7, See Chapter 31 [laos.sx.gws.drot.derotation-svr GUI.sh], page 6, See Chapter 17 [laos.dx.hws.drot.derotation-svr GUI.sh], page 5, See Chapter 9 Note that even with the combined use of the options, the subsystems still need to be specified [laos.dx.gws.drot.derotation-svr GUI.sh], page 4. explicitly right after the -d and after the -s. They cannot be placed after the -t, and they are mandatory. 67.3 Preset Star Enlargers to Park Positions licsPreset -t sx -d $INSROOT/etc/starcat.cat sx licsPreset -s all for example is erroneous because the is at the wrong position in the argument list. licsPreset -s sx The profit of this unified call is that while the telescope is slewing the derotator motors may already rewind to their optimized start positions, and the star enlargers may move to licsPreset -s dx the periphery of their field. This minimizes the overhead. licsPreset -s laos.dx.gws.se.starEnlarger-svr If the telescope is already on the intended track and one just wants to rewind the derotators licsPreset -s laos.sx.gws.se.starEnlarger-svr and re-assign star enlargers, the -t option is not used: licsPreset -s laos.dx.hws.se.starEnlarger-svr licsPreset -d all -s all $INSROOT/etc/starcat.cat licsPreset -s laos.sx.hws.se.starEnlarger-svr ... wait until derotating Moves all 4 or the two star enlargers of one side or one individual star enlarger motor to the licsStarcat -m $INSROOT/etc/starcat.cat park position. The option -s followed either by all or by a single name of a star enlarger As shown above, the start positions of the derotators are calculated by fitting a predicted server moves all four services in parallel or the one addressed by the configuration file name parallactic angle of the first star in the star catalog into the individual ranges of the motors. to a park position near the home base at the periphery of the field. It does not consider the other stars, so the distribution of the star enlargers may be awkward The cases -s all, -s sx and -s dx spawn subprocesses which execute indivdually; even if if that somewhat arbitrary start angle of the motor is actually selected. If the (experienced) one of the star enlarger sets runs into problems (e.g., because motors run into collisions or operator realizes, with the aid of Chapter 71 [licsStarcat], page 24, that star enlargers cannot services other interfaces fail), the others will continue their mission. easily grab the AO stars using that angle, he may 21 Chapter 68: licsRewind.py 22 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 51 just stop the derotation on any of the derotators with the GUI, move the motor by 68.3 Timing • the order of some 10 or 20 degrees, restart the derotation from that new position, and The action of the script is simple if -g is not used: the motor moves to the previous start re-run licsPreset to improve the layout of the SE assignments. angle, and the script is done. or alternative rerun licsPreset with the option -D to suggest a shifted start angle to • the calculation. If the -g is used, the principle of operation is that the script exits once the new derotation has started. This allows any monitoring/calling service (like GEIRS) to execute that script In summary, the preset and automated start of the derotations is aiming at a non-supervised, in the foreground, and to continue on the basis that the derotation is active as the script has fully integrated design of the operation. terminated. This implicitly synchronizes that monitoring service with the derotation. To implement this timing if -g is used, licsRewind.py first rewinds to the previous starting 68 licsRewind.py position, then pushes the derotation into a background process, and (clumsily) figures out by watching the derotators angle and motor motion flag whether derotation started. Once licsRewind.py -g -D duration/seconds -t delay/seconds the derotation seems to be active or after watching the derotator status for a maximum of 10 seconds, the script exits. 68.1 Command line options That split of the actions into a pure flyback plus a start of the derotation allows amore robust timing, because the flyback may take as long as it needs to reach the previous The command (and Python script) rewinds the derotator motor of the infrared camera to position, and (we pray that) the overhead of downloading the derotator polynomials from the position it had at the start of the previous derotation, and optionally starts a derotation the telescope and uploading to the motor can be predicted as some constant proportional there based on the parallactic angle polynomials it gets from the telescope interface. to the length of that trajectory. (The polynomials need to be scheduled for some time in The option -g (meaning ’go’) triggers that another derotation stars after that preset motion the future, and the motor interface refuses to start if it observes that it needs longer to to the previous start position. push them to the motor electronics than that start of the trajectory. So there are still fudge The option -D followed by a number which is a duration in seconds indicates how many factors here that are not nicely predictable because the internet connection speed from the seconds of the upcoming trajectory should be requested from the IIF interface. If the option derotator service may differ by some 2 orders of magnitude. In short, that scheduling ofthe is not used, half an hour (1800) is inserted. This duration only has some meaning if the -g start of the trajectory must take some high estimate of how much time that down/uploading is also used. of the trajectory may need.) The option -t followed by a time in seconds can be used to schedule the start of the derotation by some delay into the future. If the option is not used, the program tries to use 68.4 GEIRS Interface a small delay sufficient to retrieve the trajectory polynomials from the IIF and to upload them to the motor controller. This delay has no meaning unless the -g is also used. The relevance for the readout of the Linc-Nirvana infrared camera (IRC) is as follows: There is a generic mechanism in GEIRS (versions 779 and later) to execute any com- 68.2 Rationale mand just before the read, the readout of the detector, starts. GEIRS always calls the executable QueueEFiles which resides in the GEIRS/scripts directory of the GEIRS user. Each derotator service stores its motor start angle in its private property tree when dero- This QueueEFiles can be any executable and is a shell script in our case. This shell script tation starts, so it can recall this angle to move (absolutely) there. This is implemented in asks GEIRS (via the GEIRS command interface) whether the endless flag of the GEIRS the rewind BASDA interface of the derotator services. The first value of that angle usually exposure is set. stems from the previous call of licsPreset, so it is quasi optimized for the trajectory of the parallactic angle associated with the current target, and can generally be reused for If that endless flag is set, GEIRS does nothing (assuming that it would be not usefulto trajectories in the near future without a risk of hitting some motor limits. guess how long this chain of exposures may last, and assuming that this mode is rather The aim of the rewinding procedure is to keep the motor angles used by the infrared used to adjust telescope focus and other optics in interactive GEIRS sessions). camera near a small interval such that any speckled infrared background in the optics (that If the endless flag is not set, the QueueEFiles asks GEIRS how long the exposure will last unfortunately will be rotating while derotating the objects images) is quasi constant for all (including the repetition factors), adds 10 seconds as a buffer time (roughly related to the exposures. That should simplify subtracting such instrument background from the images. fuzzy timing mentioned above), and calls licsRewind.py to rewind to start a trajectory Rotating the infrared detector is obviously a simpler operation than manipulating the dero- lasting for that prolonged exposure time. tation of the other 4 AO subsystems, because no reaquistion of star enlargers is involved. Note that the derotator service of the IRC does not know anything about the status of Example: GEIRS. GEIRS always calls QueueEFiles at the start of each exposure, and that shell script # rewinds the derotator motor and starts a derotation that will last 40 seconds. either tries to modify the derotation by calling licsRewind.py based on further information licsRewind.py -g -D 40 it can gather from any services, or it does not.

23 24

To disable that automated rewind/derotate mechanism of GEIRS, either put Because the log files are created on the computer that runsthe SE service, one usually needs all lines in QueueEFiles into comments, or add a line exit 0 near the top of to run the script on laos2. ~/GEIRS/scripts/QueueEFiles on lircs.linc.lbto.org, such that QueueEFiles does The syntax: nothing and returns immediatly. Alternatively you can also tell the licsRewind.py to do nothing by adding a quit() early in $INSROOT/bin/licsRewind.py on lircs.lin.lbto.org. Without command line argument, the script scans the 4 log files of the 4 services. • In GEIRS versions >= 779M-15 there is a check box -Q in the controls GUI right off With two command line arguments, the first option is expected to be either sxor the read button that tells GEIRS to use or to ignore the entire QueueEFiles call. This • dx, and the second either gws or hws. This constructs the log file name using the means for Linc-Nirvana, the GEIRS operator can decide prior to each read whether the environment variable INSROOT and scans that log file. rewind mechanism is executed or not. If the check mark at the box -Q is set, GEIRS calls With one command line argument, the file with that name is scanned. QueueEFiles and the detector motor rewinds to its previous location at the next read, • otherwise GEIRS does not call QueueEFiles and the detector derotation is not affected. The standard output contains a time stamp (first field the date, second the time of theday, (Not affected means it continuous on its trajectory whatever that currenly maybe.) currently the local time zone because this is the standard of the Linux machines), and then A first step of debugging this rewind mechanism is to testthat licsRewind.py and blank-separated x and y coordinates of the SE heads in the order SE01x, SE01y, SE02x, QueueEFiles work as expected; These are part of the Linc-Nirvana source package, not of SE02y,... in units of microns. GEIRS. The script tries to eliminate log lines that are generated while observers run the SE positions through the associated GUI or with search scripts. This is implemented by configuring a 69 licsSEOffset.py time span of currently 90 seconds (as a variable in the script), and printing log lines only if there is no other SE motion activity within that time span into the future. licsSEOffset.py --CONFIG=.. --LOGLEVEL=... deltax deltay If a plot over these positions as a function of time is desired, and supposed the output of The command selects a subset of the 8 or 12 star enlargers of one of the four fields (GWS, licsSEhist.pl has been redicirected to SE.txt, one can call gnuplot and enter HWS, SX, DX) and moves the active star enlargers by the same relative amount in their set timefmt "%Y-%m-%d %H:%M:%S" global x-y coordinate system. The last two parameters are numbers in units of microns set xdata time detailing how much along the two orthogonal coordinate systems (+x and +y) the SE’s set xlabel "time" should be moved. set ylabel "x" The initial parametes are Twice-As-Nice standard parameters. The CONFIG parameter set zlabel "y" selects which of the SE sets are actually addressed. # set yrange [-150000:150000] The command is currently called from within See Chapter 65 [licsOffset], page. 12 See that # set zrange [-150000:150000] section for potential problems with large offsets. licsOffset takes care of mapping differ- # set clip two ential positions in the equatorial coordinate system to SE image planes, and of reversing set style data points the direction of the offsets to align telescope offsets with SE offsets. splot "SE.txt" using 1:3:4 title "SE01", \ licsSEOffset.py --CONFIG=~/lnsw/config/laos/sx/gws/se/laos.sx.gws.se.starEnlarger- "SE.txt" using 1:5:6 title "SE02", \ svr.cfg 0.0 3.0 "SE.txt" using 1:7:8 title "SE03", \ "SE.txt" using 1:9:10 title "SE04", \ "SE.txt" using 1:11:12 title "SE05", \ 70 licsSEhist.pl "SE.txt" using 1:13:14 title "SE06", \ "SE.txt" using 1:15:16 title "SE07", \ licsSEhist.pl "SE.txt" using 1:17:18 title "SE08", \ licsSEhist.pl sx gws "SE.txt" using 1:19:20 title "SE09", \ "SE.txt" using 1:21:22 title "SE10", \ licsSEhist.pl dx gws "SE.txt" using 1:23:24 title "SE11", \ licsSEhist.pl sx hws "SE.txt" using 1:25:26 title "SE12" licsSEhist.pl dx hws licsSEhist.pl $INSROOT/var/log/laos.sx.gws.se.starEnlarger-svr.log The script extracts SE plane positions for the 12 or 8 SE heads from the current file in the 71 licsStarcat $INSROOT log directory. Chapter 71: licsStarcat 25 Chapter 71: licsStarcat 26 52 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 71.1 Submit to Star Enlargers 71.1.4 Option t The -t option specifies a time stamp of an observation at which the conversions for proper 71.1.1 Syntax motions and parallactic angle should take place. The four supported formats of the argu- licsStarcat [-f limitmag [-t [YYYY-MM-DDT]HH:MM:SS... ] [-s sx|dx ] [-g hws|gws ] ment are: { } { } [-G gwsmotang/deg] [-H hwsmotang/deg] [-K] [-m fil1.cat [file2.cat ...] It contains an ISO (https://en.wikipedia.org/wiki/ISO_8601) specification of the Merges one or more of the LBTO star catlog ASCII files, optionally applies a cut onthe • time: the 4-digit year, the 2-digit month, the 2-digit day of the month, a T and the brightest magnitudes that should persist, sorts the resulting stars by distance from the first, hour, minute and second, separated by dashes, the T and colons as indicated. The and writes the merged catalog to standard output (likely to be redirected into another file). seconds should be followed either by a Z to indicate Zulu (UTC) time, or a sign and The program attempts to contact the up to four derotator servers to retrieve the motor hours and minutes for the time zone offset. Use for example -t 2017-10-11T03:03:00Z angles, the TCS proxy server for the parallactic angle, to assign the catalog stars to Star to assume observation in the early morning in UTC of October 11. Use for example -t Enlarger arms, and to submit the coordinates to the SE servers so the proposed SE positions 2017-10-11T03:03:00-0700 to assume observation in the early morning of October appear in the operator’s GUI. 11 in the Arizona time zone, which is 7 hours west of UTC all year long. If the local The usual application of this call is that only a single input file (in the LBTO star catalog computer is running in some other time zone, use date -u or timedatectl to obtain format) is specified, where the interest is in the comments in the output that containthe the current time in UTC. distances to the target and the SE coordinates and assignments, for example It contains an hour, minute and second as HH:MM:SS; this is a time interval into the • licsStarcat -m ~/lnsw/ln/lics/tom/guider/test.catalog future relative to ’now’, where ’now’ is the time when the program is executed. Use for example -t 02:00:00 to assume observation in two hours. 71.1.2 Option K It contains minutes and seconds as MM:SS; this is a time interval into the future By default the program maps the sky (ra/dec) positions of the star catalog by standard • relative to ’now’, when the program is executed. Use for example -t 30:00 to assume transformations of spherical astronomy (neglecting refraction, including precession..) to the observation in half an hour. focal plane that is located after the the annual mirror. If the -K is used, the program tries to It contains seconds as SS; this is a time interval into the future relative to ’now’, query instead the kernel focal plane coordinates from the TCS. This has many advantages • when the program is executed. Use for example -t 20 to assume observation in twenty in principle but fails on the mountain. Do not use -K for now because it seems that there are seconds. flips of coordinates that are not understood yet; in particular the coordinates computed by If -t is absent, the time when the program is started is taken by default. This means the 2018A TCS on the mountain are not compatible with the telescope simulator sim-2016b and the CAN document 022s105. in particular that the program ought to be started after the derotators started: then the options -t, -G, -H are superfluous because the angles needed to predict SE positions can be The advantages of this FPC mediation triggered with -K are: retrieved online from the derotator services. Scale changes in the focal plane that stem from focusing mechanisms of M1, M2, or • any flexure models that are incorporated in the PCS algorithms are taken into account. 71.1.5 Option s The disadvantages of this approach are: The -s option specifies one of the two sides of the telescope, sx or dx. If the option is not The pointing control system (PCS) of the IIF must have be configured correctly (in- used, the command tries to engage both sides. Using the option to add a constraint on • cluding the M3 angle). the side is beneficial if the entire setup uses only one side of the optics (the otherhatch The response of the IIF to the queries is slow, and apparently proportional to the then usually closed), because time consuming operations are only attempted on one side. • number of stars in the catalog. It takes typically 20 seconds or longer before FPCs are Example: available. The associated problems are inpatient observers who may misinterpret this licsStarcat -s dx -m ~/lnsw/ln/lics/tom/guider/test.catalog as a hangup of the software, plus a fuzziness of time scales that comes into play because the FPC are in a coordinate system that rotates at the speed of the parallactic angle. 71.1.6 Option g The -g option specifies the AO subsystem, either hws or gws. If not specified, the program 71.1.3 Option f tries to engage both. The -f option specifies a cut to exclude targets fainter than limitmag. The default value is 30, which means effectively all stars that one could imagine in a Linc-Nirvana context are 71.1.7 Option G kept. If the star catalog has been extracted in automated ways from some servers and is The -G option specifies a nominal angle (in degrees) for the GWS bearing with the same highly populated (with typically more stars than the number of star enlarger arms), this offset as used in the GUI. If not specified, the program tries to contact the server ofthe option is a kind of manual filter that may help to put priority to the brigher stars andto GWS of the associated side(s), and if this fails the default is 0 deg, which is near the middle maximize flux in the AO detectors. of the range for both SX and DX.

Chapter 71: licsStarcat 27 Chapter 72: licsXephem 28

There is no interface to specify two different angles for SX and DX because this is a debugging Any spurious reflections or ghosts in the optical paths that appear in thepatrol option. (The derotator services should be responding in normal operation.) • camera, including temporary things like meteorites or extended sources, may lead to a false interpretation of AO targets. 71.1.8 Option H Blooming effects on the Patrcol Camera need to be taken into account whileex- • The -H option specifies a nominal angle (in degrees) for the K-mirror rotation withthe tracting the star positions. same offset as used in the GUI. If not specified the program tries to contact the server of Only the algorithm which predicts the positions without examining the patrol camera image the K-mirror of the associated side(s), and if this fails the default is 45 deg, which is near is currently available. the middle of the range for both SX and DX. There is no interface to specify two different angles for SX and DX, because this is a debugging option. (The derotator services should 71.1.11 Algorithm GWS be responding in normal operation.) The GWS SE predictions use the following procedure: The star coordinates of the catalog 71.1.9 Option b are projected along the RA and DEC directions of the target star, and forwarded to the focal plane after the annual mirror including standard spherical astronomy (parallactic angle to The -b option enters a batch mode, which in fact means that pop-up GUI’s are suppressed. obtain horizontal coordinates and the fixed +-108.5 degrees selected by M3.) These are On request of Thomas Bertram during Com-3, this option is permanently activated by a flipped horizontally to account for the annular mirror reflection, rotated by the combined cpp setting in the source code, so use or non-use of the switch has no effect. GWS motor, then adjusted for axis runout and angle offset. 71.1.10 Algorithm HWS 71.1.12 Trouble Shooting For the HWS SE predictions two algorithms are foreseen: Potential problems are: The command is issued before the derotators started their (slow) derotation, such that The current version reads the star catalog, runs its stars through proper-motion, pre- • • cession updates, filters them through the distance of 1 arcmin to the first star, derives the motor angles are not correctly retrieved and not correlated with the parallactic a total angle from K-mirror and parallactic angle, and projects these coordinates into angles as they should. Run the licsStarcat command again if that happened. the SE plane(s). The advantage of this approach are: The catalog file at the end of the command line is not the same as the one usedforthe • The operator has full control over which stars are considered candidates for the telescope preset, so the stars in the catalog are not where the telescope is looking at. • HWS AO stars. Run the licsStarcat command again if that happened. The Patrol Camera is not needed. • 71.2 retrieve The second version reads a Patrol Camera image it the associated side, runs this with • the sextractor to detect stars (a Gaussian filter with 0.8 arcsec. FWHM, signal-to-noise licsStarcat -W [-f limitmag] [-r coneraddeg] (radegrees|hh:mm:ss) (decdegrees|+- limit set to 2), and maps these positions with the coordinate transformation matrix of dd:mm:ss) 2017-03 (quasi backwards through the dichroic) to the SE plane(s). The advantages of This is a combined action of getting a part of the NOMAD star catalog (online, not working this approach are: if the server on the .mil net or the internet or any intermediate proxy are down) and Whatever the axis runouts of the K-mirrors or telescope flexures are, these are converting it to our catalog format. • implicitly taken care of because the Patrol Camera image is taken after the beam The -r option defines the search radius on the sky in degrees. The two equatorial coordinates has passed through the K-mirror. So actually the transformation matrices through either in degrees or in the hh:mm:ss and +-dd:mm:ss hex-format are the mandatory final the telescope, through the two mirrors of the HWS AO system, the reflections by parameters. The current defaults for the two parameters are the piston mirror, the warm dichroic, the 3 K-mirror reflections and the dichroic a limiting magnitude of 14 (specify after -f a value of 30 or larger to disable this that separates the patrol camera and the AO beam need not to be calibrated. • effectively) Parallactic angle and K-mirror angle are not needed. The algorithm is robust a cone radius of 0.075 deg equivalent to four arcminutes. • against jitters in time or against these servers running or against the derotator • running. 72 licsXephem It does not matter whether the operator used a wrong file argument for the star • catalog in the call, because the file is actually not needed. In the same realm, licsXephem [-a] fil1.cat [file2.cat ...] errors of proper motions and the like in the star catalog are irrelevant. Translates LBTO catalog files to the xephem (http://www.clearskyinstitute.com/ The disadvantages are xephem/help/xephem.html) format, copies this to the .xephem/linc.edb file in the home Chapter 73: liifSnapshot.py 29 30 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 53 directory, and calls xephem to show where the stars are currently on the sky. This gives a 74 liifSnapshotGUI fast impression which of the star catalog have sufficiently large elevation above the horizon at the time when the program is called (or at other times to be selected by the menu). Opens a window and shows the updated contents of the most important variables of the IIF (TCS) dictionary with pauses between updates. By default, only the first star in each catalog file is copied to the XEphem database; the option -a triggers that all stars are copied. The display is terminated by either typing CTRL-c in the window or closing the window with the X-button of the window manager. The command line arguments should be ASCII files in the LBTO format (as used elsewhere). The list of variables is the same as the one placed into FITS header keywords. It is configured It is convenient to let the Linux shell expand all cataloges in a directory with the usual wild in the file config/ltcs/ltcs.iif-fits.xml. card expansion mechanism, which means, to use an argument of the format somedir/*.cat. The meaning of the parameters is shown in http://wiki.lbto.org/pub/Software/ xephem must have been installed as detailed in LN-MPIA-MAN-ICS-010 (https://svn. SWRelBuild2018B/DDNames, or an equivalent place where year and semester refere to the mpia.de/trac/gulli/ln/archive/Archive/LN%20Documentation/Manuals%20(MAN)/ current TCS release. Instrument%20Control%20Software%20(ICS)/LN-MPIA-MAN-ICS-010.pdf). Note that this does not contact the IIF server directly but shows the values obtained by the ltcs.iif-svr, so this server needs to be running to get periodic updates of the values. (This is Use in detail: Once the xephem window pops up, click on Data and select Files. In the the same server that is used to request the derotator polynomials from the TCS. So this will new window click again on Files and select linc.edb, which has just been created by the be already running if any of the 5 derotator services for the GWS, HWS or infrared detector program. The remove the Messier.edb and KY2k65.edb with the Delete buttons in the is running.) The updates will become obvious if one looks at clock type parameters like subwindow such that only linc.edb remains. Then in the main window click on Data and UTC or LST. select Index to get an overview which stars have been loaded. (Actually on the first star of each of the LBTO catalog files has been exported to avoid that the view gets too crowded. The catalog appears twice: (i) with the base file name, and (ii) with the type name which 75 lircs.moe-svr GUI.sh was the first field of that star in the LBTO catalog.)

Then in the main window on Viewer and select Sky view, click at the left on the cylinder to lircs.moe-svr_GUI.sh get a display that is close to the natural alt-az system. Optionally click on the Cos symbol lircs.moe-svr_GUI.sh start in the menue to remove the constellations contour lines. The click repeated times on the lircs.moe-svr_GUI.sh stop top light bulb to let the stars of our additional catalog appear in the order of magnitudes. The usage without the command line option is the same as the usage with the command (It seems one must repeat that brightness adjustement each time the zoom scale is changed line option start with the left slider and also after some other modifications...) This opens/closes 5 windows related to the movable optical elements in the cryostat: In the GUI with the index one can click on one or more of the stars and then on Sky Point lircs.moe.fwr GUI for the filter wheel in front of the IR detector to get it marked in the image window. • lircs.moe.dwr GUI for the dichroic in front of the FFTS • licsXephem /data/2017-06-Com2/targetlists/bestof_starrings10mag/*.cat lircs.moe.smc GUI for the secondary mirror in the cold. This comprises the 3 degrees • of freedom of the tip-tilt and focus of the three pistonic axes. lircs.moe.dpos GUI for the sideways detector position stage. According to a system 73 liifSnapshot.py • engineer’s comment after Com-5 these two motors will essentially never be moved once aligned with the optical axis, because that shifts also the derotator axis sideways and effectively destroys the design of the derotator. lircs.moe.drot GUI for the derotator stage liifSnapshot.py [+g] • Print an overview of the IIF variables in the current state. 76 lnDeployAtLbt.sh The set of variables that is shown can be changed by commenting the items of the very long list in the source code of liifSnapshot.py in or out.

If the option +g is added, a rough snapshot of the current derotator polynomials is also 77 lnDeployAtMpia.sh printed.

31 32

78 lsfits 83 lsysChkNTP.sh lsfits Runs a date command on the ln-xi PC’s and the Linc-Nirvana servers laos, laos2, lsys, lsfits fitsfile.fits lsys2 and lircs. This is mainly a rough test that the system clocks are all NTP-adjusted to an accuracy of 1 or 2 seconds. lsfits fitsfile.fits[extensionspec] Print headers of FITS files listed by the command line arguments. The command line argument can be a FITS file name and headers of all extensions are printed. Itcanbea 84 lsysCryostatControl.py header index in brackets, starting with index 0 for the primary header. It can be a header name in brackets. lsysCryostatControl.py startcooldown Note that the Linux shell tries to expand these brackets; one must usually quote these lsysCryostatControl.py stopcooldown bracket expressions. lsysCryostatControl.py startwarmup lsfits hugo.fits lsysCryostatControl.py stopwarmup lsfits hugo.fits’[1]’ lsysCryostatControl.py startregeneratezeolithe lsfits hugo.fits’[GTI]’ lsysCryostatControl.py stopregeneratezeolithe On computers where GEIRS is installed, one may as well use dfits. On computers where lsysCryostatControl.py startfftsbptc the heatools are installed, one would prefer to use the more versatile ftlist. lsysCryostatControl.py stopfftsbptc 79 lsys.cab.int-svr GUI.sh Sets the cryostat controler parameters to start or stop the cooldown or warmup procedure. 85 lsysWebCameraControl.py

80 lsys.cab.ps-svr GUI.sh lsysWebCameraControl.py off lsysWebCameraControl.py on This GUI offers buttons to switch power on or off in subunits ofthe6 LN control racks where they are assessible by switchable power lines. The button in the upper right corner lsysWebCameraControl.py sx switches all of these individual power lines at the same time. lsysWebCameraControl.py dx There is a button for the ROE-NIR which acts on the read-out electronics rack of the lsysWebCameraControl.py mpia NIR detector. There is no risk to interrupt the heater control loop of the Hawaii-detector lsysWebCameraControl.py localhost here because that power is hooked up on the UPS and not switchable here. However, we know that the power of the ROE basically feeds the pre-amplifiers of the detector outputs, and if these are switched off the detector unit will usually be cooled below the operative 86 ltcs.iif-svr GUI.sh temperature of the pre-amps, and one may need up to 5 hours to return to normal operation of the science detector. In short: do not switch off that ROE-NIR power during those A display of the most important TCS pointing information. stretches of days/nights when Linc-Nirvana operations are scheduled to use the science detector, but do swith off that ROE-NIR power while the instrument is cooling downor 87 plotSkyTrack.py warming up. The associated hardware switches are in the LN Power off Page (http://wiki.lbto.org/ Plots the parallactic angle and the altitude and azimuth for the next 20 minutes assuming bin/view/Instrumentation/LnPowerOffPage) . sidereal tracking. The IIF is regularly polled for the current information to update the plot. 81 lsys.cryo.int-svr GUI.sh It gives a hint of how longer the derotator stages may stay tracking before hitting their limit switches.

82 lsys.ffts.int-svr GUI.sh 88 setTargets.py 33 54 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 89 start nirvana new

The command start_nirvana_new starts the detector control software, GEIRS. The com- mand can only be executed on the machines where the software is installed, usually lircs and as a backup lsys2. The detector can only be read out from computers where the associated interface boards are installed and connected to the detector, lircs or lsys2. The description of that subsystem is in LN-MPIA-MAN-ICS-007 (http://www.mpia.de/ homes/mathar/public/LN-MPIA-MAN-ICS-007.pdf) .

Index

(Index is nonexistent) LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 55

5 IR OPTICS

5.1 Atmospheric Dispersion

An estimate of the transverse chromatic atmospheric dispersion (TAD) is obtained from the first approximation R = (n 1) tan z [25], where R is the difference in the apparent and true zenith − angles in radian (at 1 rad 20626400), z the zenith angle, and n the real part of the refractive index ≈ of air. Estimated values of the refractive index at the observatory are shown in Figure 13. They illustrate the (tiny) influence of water content in the atmosphere which was missing in the earlier report [26].

1. The first result is that since n 1 is of the order of 1.9 10−4, R is of the order of 3900 tan z. This − × may lead to an (apparent) distortion of ∆R 1.9 10−4(1 + tan2 z)∆z over the field of view. ≈ × LN covers ∆z 2048 0.00500 1000, so at an average tan z 1 the relative linear distortion ≈ × ≈ ≈ accross the field relative to astronomical catalogues is ∆R 2 1.9 10−4 1000 0.00400. ≈ × × × ≈ 2. The second result is that, even if no filters are used, the full chromatic dispersion over all relevant infrared bands is ∆n 4 10−7, the associated ∆R is 0.0800 tan z. At a pixel scale ≈ × ≈ of 0.00500 of the science detector, these are 16 pixels. The dispersion between the red and the infrared bands is of the order of ∆n 2 10−6, the ≈ × associated ∆R is 0.400 tan z. Given the pixel scale (31) on the guiding camera, this is a ≈ natural offset by 3 pixels between patrol and science channels.

1.930e-04 40 65 80

1.925e-04

1.920e-04 Re n -1 1.915e-04

1.910e-04

1.905e-04 0.8 1 1.2 1.4 1.6 1.8 2 2.2 2.4 λ (micron)

Figure 13: Real part of the refractive index at 690.0 hPa (the typical LN atmospheric pressure), 7 ◦C and three different relative humidities between 40 and 80% [27]. 56 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044

6 TROUBLE SHOOTING

6.1 FAQ

1. Q: What is the relevance of source files occuring at different places with the same name, like

/doc/include/Nice/Qt/SetIconSearchPath.cc ./doc/include/Nice/Util/FileByPath.h ./doc/include/Nice/Util/FileByPath.cc ./src/libNice/Nice/Util/FileByPath.h ./src/libNice/Nice/Util/FileByPath.lo ./src/libNice/Nice/Util/.libs/FileByPath.o ./src/libNice/Nice/Util/.deps/FileByPath.Plo ./src/libNice/Nice/Util/FileByPath.cc

A: The files in the doc subdirectories are only (old) versions used to create documentation for doxygen and therefore irrelevant to real applications. To remove these insert

NODYXYGEN = true

in the Makefile.am of the associated directory so doxygen is not called during make.

2. Q: Why are there old 149.*.*.* IP-Adresses at many places in the .cfg files of TwiceAsNice? A: These are remnants of old test configurations. These are not actually relevant because the LN configuration files are kept in the separate ln/config subversion folders.

3. Q: In my python program the import Ice emits an error

ImportError: dynamic module does not define init function (initIcePy)

A: You may need to enforce an explicit Python interpreter if Ice was compiled for another Python version. Either edit the

#!/usr/bin/env python

at the header of the python file (discouraged because often these scripts are distributed across various computer platforms) or call an explicit version with

python3.4 .....py

4. Q: How can we reverse-lookup the IP addresses in the log-files to computer names on the subnets? A: The IP table is in trac.

5. Q: How is the simulating (dummy) IIF server switched in that is a substitute of the LBTO IIF server? A1: Replace the alias file to point to the simulating servers and start the simulator: LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 57

cd ~/lnsw/config rm alias.cfg ln -s alias-localhost.cfg alias.cfg LbtoIIFSimulator --LOGGER.LEVEL=INFO --CONFIG=ltcs/ltcs.iifDummyLocalhost-svr.cfg &

Replace the ltcs.iif-svr.IIF end point of the derotation services by ltcs.iifDummyLocalhost- svr.IIF in the five config files of the motors:

./laos/sx/hws/drot/laos.sx.hws.drot.derotation-svc.cfg ./laos/sx/gws/drot/laos.sx.gws.drot.derotation-svc.cfg ./laos/dx/hws/drot/laos.dx.hws.drot.derotation-svc.cfg ./laos/dx/gws/drot/laos.dx.gws.drot.derotation-svc.cfg ./lircs/drot/lircs.moe.drot-svc.cfg

A2: The better solution is proposed in Section 7.1.1. The LBTO telescope simulator responds which much more realistic timing to the various queries than our hand-sewn lbtoIIFSimu- lator.

6. Q: Which GUIs are there? A: See the output of

info linc

or call

find ~/lnsw/config/scripts -name "*GUI.sh" | sort

7. Q: I want to open firefox but this is already used by someone else under the same user name on the same machine. A: Use opera instead.

8. Q: ICE complains about ports already in use but does not show which ones. A: To get this information one needs to recompile ICE and insert a line that shows which connection it is trying to establish. One needs to insert a debugging output near the bind call in the function doBind in the file cpp/src/Ice/Network.cpp that roughly looks like

std::cerr <<__FILE__ << " " << __LINE__ << " bind " << IceInternal::addrToString(addr) \ << " fd " << fd << std::endl ; if(::bind(fd, &addr.sa, size) == SOCKET_ERROR) ...

7 EXTERNAL SOFTWARE

7.1 LBTO SW

The external LBTO software is covered by http://wiki.lbto.org/bin/view/Software/WebHome, http://wiki.lbto.org/bin/view/Instrumentation, and sections 4xx of http://abell.as.arizona. edu/~hill/xlbt/can.htm. 58 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044

7.1.1 Telescope Simulator

7.1.1.1 Oracle’s VirtualBox A virtual machine for the TCS simulator software is set up with zypper install virtualbox zypper install libvirt-daemon-vbox libvirt-daemon-driver-vbox Then remove the usb lines in /etc/udev/rules.d/60-vboxdrv.rules. Then reboot the host computer such that the /dev/vboxdrv exists. Obtain the VM software from http://people.lbto.org/~shooper/TCS.ova. cd ’VirtualBox VMs’ mkdir TCS cd TCS wget http://people.lbto.org/~shooper/TCS.ova . With the call VirtualBox and clicking on File load Appliance this is installed as a virtual machine. Additional instruc- → tions are in http://wiki.lbto.org/bin/view/Software/UsingTCSSimulatorAppliance. For openSuse use yast2 User and Group management to add the required users (lneng, nirva, → . . . depending on the environment) to the vboxusers group. Note that this group is not initially shown but in the list that displayed after selecting Filters System users. You probably need → to log out and in to be allowed to start the virtual machine19

7.1.1.2 At LBTO On the mountain, the virtual machine starts the TCS simulation on the IP address 192.168.156.48. The configuration of the VM in the VirtualBox Manger is::

In File Preferences Network leave the NAT Networks and Host-only Networks empty • → → In Settings Network select the Bridged Adapter on em1, where em1 is the OpenSUSE • → interface board on the host.

In /etc/hosts we have • 127.0.0.1 localhost localhost.localdomain localhost4 localhost4.localdomain4 ::1 localhost localhost.localdomain localhost6 localhost6.localdomain6 127.0.0.1 tcs-sim.linc.lbto.org tcs-sim.linc tcs-sim 192.168.156.48 tcs-sim.linc.lbto.org tcs-sim.linc tcs-sim 192.168.156.40 lsys.linc.lbto.org lsys.linc lsys 192.168.156.231 ln-x1.linc.lbto.org ln-x1.linc ln-x1

The class-A network for a host on mountain.lbto.org may be commented and is not useful in simulation.

In /etc/hostname we have a single line • 19see the permissions on VBoxHeadless on openSUSE 13.1 for example LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 59

tcs-sim

In /etc/resolv.conf we have • search linc.lbto.org nameserver 192.168.156.40

In /etc/sysconfig/network we have • NETWORKING=yes HOSTNAME=tcs-sim DNS1=192.168.156.40 SEARCH=linc.lbto.org

In /etc/sysconfig/network-scripts/ifcfg-enp0s3 we have • NAME="enp0s3" DEVICE="enp0s3" ONBOOT=yes DHCP_HOSTNAME=tcs-sim NETMASK=255.255.255.0 UUID=... IPV6INIT=yes BOOTPROTO=none IPADDR=192.168.156.48 TYPE=Ethernet DEFROUTE=yes IPV4_FAILURE_FATAL=no IPV4_AUTOCONF=yes IPV6_DEFROUTE=yes IPV6_FAILURE_FATAL=no DNS1=192.168.156.40 DOMAIN="linc.lbto.org" PEERDNS=yes PEERROUTES=yes IPV6_PEERDNS=yes IPV6_PEERROUTES=yes

All of this configuration has already been done on ln-x1. So for the operator who wants to test the software without actually having access to the telescope (interface), the action is to type VirtualBox & on the ln-x1 Linux command line, to click on the green Start arrow in the menue, or all in one VirtualBox --startvm TCS & VBoxHeadless --startvm TCS & # openSUSE 13.1 60 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044

Figure 14: The TCS 2018A simulator as seen with the vncviewer just after start-up. and to watch the virtual machine booting until the root@tcs-sim-prompt appears in its local win- dow.20 If questions pop up concerning security holes for USB putthrough, disable that feature (we don’t work with USB on the virtual machine.) After starting the virtual machine one should be able to ping 192.168.156.48 from lsys and from ln-x1, and be able to ping 192.168.156.40 on the console of tcs-sim. Install the vncviewer with yum/zypper and run vncviewer 192.168.156.48:0 & to open the LBT TCS Control GUI. Press the 8 individual Start buttons or just the button to start all subsystems, from LSS to OSS. Acknowledge the Continue question. Watch the buttons to turn green in about a minute.21 In the subsystemes area open the IIF control GUI, the PCI control GUI and optionally the MCS GUI by pressing the associated GUI buttons.22 Click on the

20Once the virtual machine has booted, the VirtualBox Manager window and that console window of the virtual machine can be minimized to save space. 21Ignore messages related to misconfigured swing arms, side monitors and other subsystems. . . 22If they don’t pop up, make sure that the vncviewer window is big enough because new windows may hide in LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 61

Control button in the IIF GUI to authorize LINC on one or both sides of the telescope, which means pull-down to select LINC or NONE and click on Authorize; if one of the two arms is authorized for None, its correlated region in the PCS area will disappear. The GUI then looks similar to Figure 14. Edit the endpoint in the TaN configuration file config/ltcs.*.iif-svc.cfg on lsys to replace the HOST iif.mountain.lbto.org by 192.168.156.48 and restart the associated LN IIF server so it communicates with that host for the tests.

7.1.1.3 Networking Example MPIA This here illustrates the setup for the virtual ma- chine (named tcs-sim) on an openSuse host (named irws2) where the virtual machine needs only to be accessed from that single host (which runs TAN). So the assumption is that the VM does not need to reach the mpia-hd.mpg.de network. We set up a subnet 192.168.56.x (named irws2.mpia-hd.mpg.de on the host in which the only computers are irws2.irws2.mpia- hd.mpg.de (192.168.56.1) and tcs-sim.irws2.mpia-hd.mpg.de (192.168.56.100).

On the host irws2 set up a local DNS server: • – zypper install -t pattern dhcp dns server zypper install bind bind-utils zypper install dnsmasq dnsmasq-utils yast2-dns-server – with yast2 DNS Server enable Reload after saving... and Start During System → Boot. In the Forwarders forwarder list use the standard DNS servers (for example 149.217.41.6, 149.217.40.8 and 149.217.41.10). In the DNS Zones add two new zones (type Master), (i) irws2.mpia-hd.mpg.de and (ii) 1.56.168.192.in-addr.arpa . – with yast2 Hostnames add → 192.168.56.1 irws2.irws2.mpia-hd.mpg.de irws2 ∗ 192.168.56.100 tcs-sim.irws2.mpia-hd.mpg.de tcs-sim ∗ to the existing list. – with yast2 Network Settings Overview add a device with the Name Ethernet → → Network card, the IP Address 192.168.56.1 and the Device vboxnet0. Under Rout- ing add in the table for the destination 192.168.56.100 the Netmask /8 and the Device vboxnet0.

Start the VM on the host with VirtualBox. • – In the File Preferences Network menu leave the NAT Networks blank, goto Host- → → only Networks, click on + to add vboxnet0, then on the screw driver symbol to edit the Adapter 192.168.56.1 and the IPv4 network mask 255.255.255.0. Do not enable the DHCP Server. – In the Settings Network select Adapter 1, enable it, attach to Host-only Adapter → and Name vboxnet0, with advanced settings to Allow All and Cable connected. – In the VirtualBox menu Start the TCS VM. Add in /etc/hosts the two lines 192.168.56.100 tcs-sim.irws2.mpia-hd.mpg.de localhost tcs-sim 192.168.56.1 irws2.irws2.mpia-hd.mpg.de irws2 hidden regions. . . 62 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044

Put a sharp (#) in front of the line that contains mountain.lbto.org because this should not be accessed remotely. Check that the /etc/hostname is tcs-sim. In /etc/resolv.conf add nameserver 192.168.56.1

In /etc/sysconfig/network add NETWORKING=yes GATEWAY=192.168.56.1 HOSTNAME=tcs-sim.irws2.mpia-hd.mpg.de

In /etc/sysconfig/network-scripts/ifcfg-enp0s3 change BOOTPROTO=dhcp to BOOT- PROTO=none. Set IPADDR=192.168.56.100, PREFIX=24, GATEWAY=192.168.56.1, DNS1=192.168.56.1 and DOMAIN=irws2.mpia-hd.mpg.de. The same settings can probably also edited by calling /bin/nmtui. – In the CentOS7 command line on the VM the simulator ought to be already alive: ps -elf | fgrep mcs

The standard tests are:

1. on the host one gets a valid response from nslookup tcs-sim irws2 and from ping tcs-sim (at least after the VM has been started).

2. on the host one gets the main TCS GUI from vncviewer tcs-sim:0.

3. on the terminal of the VM one gets a valid output from ping irws2.

The major test is that the licsPreset command for the telescope lets the reddish error number in the PCS menue run down to zero and turn green once tracking. (This will not happen for example if the target coordinates are below the horizon, if authorization was faulty or if the licsPreset did not comply with the policies of the binocular control of the TCS.) If one clicks on the Source details within the PCS GUI, the target coordinates, proper motions, magnitude and so on of the Target should align with the characteristics of the first entry in the star catalog that was used for the Preset.

7.1.1.4 Shutdown Because the VM will probably keep a full processor of its host machine busy, it is explicitly recommended to shut it down when no longer needed! Once the tests with the virtual machine for the telescope are finished,

1. Click on Stop all subsystems in the TCS Control GUI of your vncviewer which will turn all backgrounds red there after a while. This action is actually superfluous. You might even before click on End of Observing before in the IIF Control GUI. Close the vncviewer GUI.

2. type shutdown now after the root@tcs-sim-prompt in the VM shell as if this were a real computer. (This usually requires to acknowledge that the virtual machine grabs the mouse LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 63

pointer. . . ). This is not really required but lets the associated desktop of the virtual machine disappear and avoids that the VirtualBox Manger asks later on whether it should save the status of the machine somewhere on disk. The desktop window should disappear and the status in the Virtual Box Manager GUI turn to Powered Off.

3. Click the File exit menue in the Oracle VirtualBox Manager GUI to close it. → 4. Don’t forget to restore the standard Twice-As-Nice configuration files with the host iif.mountain.lbto.org and to re-start the service(s) that use(s) that configuration!

7.1.2 Telescope ICE Interface

The general description of the software interface is Biddick’s 481s013 [19]. We comment on various not-so-obvious undocumented features of the software.

7.1.2.1 OffsetGuiding The value for the offset sent from the instrument to the interface rep- resenting the AZ coordinate must be the product of the change in the azimuth by the cosine of the elevation (ALT), not the bare AZ value. This is aligned with the standard interfaces of proper motions and other features in differential coordinate systems of star catalogues. Both the AZ and the ALT component must be in radians. The ALT component must be provided with the oppo- site sign (!) of what is intended. This means whereas a positive value of the AZ increases the mid-point along the azimuth, a positive value of the ALT decreases the mid-point along the alti- tude/elevation. That add-hoc sign flip appears for example within the function SetGuideOffset in the file AG Utils.py in the LN Autoguider. The server side does not accumulate values obtained by subsequent OffsetGuiding commands, but regards them as corrections relative to a fixed zero-offset defined at preset-time. So if you send a ∆a = 5 10−7 and then a ∆a = 2 10−7, the telescope selects a section on the sky which is at × − × ∆a = 2 10−7 rad (actually +2 10−7 including the internal sign flip) away from where it was − × × at the start of tracking. The LN autoguider lets the observer define intially a reference point (“hot spot”) on the patrol camera, measures in a loop basically the actual position of some star, and computes a vector pointing from the reference to the measured position. In that sense the computed vectors are already accumulated offsets and should be send as such, without adding them up and without another additional flip of the signs of the offset, to the OffsetGuiding. The python programs of the LN autoguider do all rotations in a tangential plane around the current beam center. Because the telescope interface requires bare numbers in flat two-dimensional projections, including the cosines of the latitudes of the spherical coordinate systems, all these computations are a sequence of pure rotations, flips and radial scalings, and scalings with the cosines of the latitudes disappear.

7.1.2.2 OffsetPointing2 The value for the offset send from the instrument to the interface representing the RA coordinate must be the product of the change in the right ascension by the cosine of the declination (DEC), not the bare RA value. This is aligned with the standard interfaces of proper motions and other features in differential coordinate systems of star catalogues. Opposite to the OffsetGuiding, the signs of both coordinate requests are as expected: a positive value of the parameter increases α or increases δ. Because currently the telescope’s server does not allow to send (relative) pointing offsets in the 64 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044

δ ky

α

τ 90−τ

kx

Figure 15: The coordinates (kx, ky) of the KFP system are obtained from the coordinates (f cos δ∆α, f∆δ) by an effective complementary angle τk, or a rotation by π/2 τk. −

AZALT system23, one must actually take the AZALT coordinates, rotate them to the RADEC system on the client side with (7), which differentially, linearized to first order, is effectively a rotation by the parallactic angle (27), and send these RADEC delta parameters to the telescope. It obviously helps that the cosine factors in those azimuthal components are integrated into both “tangential” projections: that local transformation is actually a pure rotation (including a flip depending on which of the coordinates are regarded as the “upper” and “lower” components). This client-side rotation is for example implemented within the SetOffset function in the file AG Utils.py in the LN Autoguider.

7.1.2.3 Kernel Focal Plane Coordinates The kernel focal plane coordinates (kx, ky) of a star are (by some heuristics) related to the position coordinates (f∆δ, cos δ∆α) by aligning δ with +ky and α with +kx, and introducing the angle

◦ ◦ τk = Rz 90 = 18.5 (73) | | −

—the same for SX and DX— [13, Fig. 6 and 8]. The definition of τk is illustrated in Fig. 15. To obtain the coordinates in a right-handed α δ system from a right-handed kx, ky system one must − employ a rotation of the coordinate system by π/2 τk: − ! ! ! f cos δ∆α cos(τk π/2) sin(τk π/2) kx = − − − . (74) f∆δ sin(τk π/2) cos(τk π/2) · ky − −

! ! ! f∆δ sin(τk π/2) cos(τk π/2) kx = − − f cos δ∆α cos(τk π/2) sin(τk π/2) · ky − − − ! ! cos τk sin τk kx = − . (75) sin τk cos τk · ky

This can be inserted into the r.h.s. of (61) to obtain the transformation from kernel-focal-plane coordinates to SE planes.

23Michele De La Pena, priv. commun. to Tom Herbst LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 65

The drawback here seems to be that the TCS Build 2018A uses a coordinate system that differs from the one in the simulator 2016B and the one described above. There is at least one additional sign flip. During LN commissioning in January and April 2018 this lead to massive problems of employing these coordinates for SE acquisition purposes. Because the team does not have surplus telescope time to debug these numbers, the LN instrument control software does not the use the focal plane coordinates since the second day of COM-4.

7.2 Python

If which pip returns nothing, installation of pip on Centos 7.2 is done with curl "https://bootstrap.pypa.io/get-pip.py" -o "get-pip.py" python get-pip.py Errors from python of the type Import Error: No module named astroplan can be met by installing the module with pip install --target=$INSROOT astroplan These python modules are evolving quickly; upgrades are done with pip install --target=$INSROOT --upgrade astroplan and it’s useful to run pip list --outdated once in a while. To install a recent (!) matplotlib get the required png library yum install libpng-devel pip download six pip install --target=$INSROOT six-1.10.0-py2.py3-none-any.whl git clone git://github.com/matplotlib/matplotlib.git cd matplotlib python setup.py install

7.3 Xephem

7.3.1 Installation xephem is obtained from http://www.clearskyinstitute.com/xephem/ and compiled with gunzip xephem-3.7.7.tgz tar xf xephem-3.7.7.tar cd xephem-3.7.7/GUI/xephem 66 LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 yum install motif-devel # for CentOS zypper install motif-devel # for openSUSE make alias xephem=’(cd ${HOME}/xephem-3.7.7/GUI/xephem; ./xephem &)’ rm ../../../xephem-3.7.7.tar mkdir -p ${HOME}/.xephem and called with xephem & For use with licsXephem one should add export XEPHEM_HOME=${HOME}/xephem-3.7.7/GUI/xephem to $HOME/.bashrc. Additional star catalogues can be compiled following these instructions. There is not much use of loading FITS images into XEphem, because ds9 seems to cover an equivalent set of tools. The FITS images created by most GEIRS patterns are of the BITPIX = 32 type, but XEphem only accepts BITPIX= 8 or 16 or -32. So as an intermediate step one needs to convert the pixels with the heatools (see the Appendix of [1]) akin to chimgtyp GEIRSfile.fits tmp.fits FLOAT The new file tmp.fits has BITPIX = -32 and is accepted by XEphem. (View sky view → → Images Load and Save). →

7.3.2 LBTO parameters

Click on the Local button click on the Chicago, Illinois button, and in the new window on create and set LBT, Arizona for the Site name, Latitude to 32:42:05, Longitude to 109:53:21 (West is positive here in XEphem!), Elevation to 3221, Zone name to MST with Offset to 7, DST name to MST with Offset to 7 24. Click on Set main and Save and Close. Under Local set the Atmospheric pressure to 681 hPa and click Update. Under Preferences set the time zone to UTC. To get an overview, click on View and select the overview. Alternatively insert into $HOME/.xephem/XEphem the lines XEphem.Elevation: 3221.0 m XEphem.Lat: 32:42:05 XEphem.Long: 109:53:21 XEphem.Pressure: 681 hPa XEphem.Sitename: LBT, Arizona XEphem.TZName: MST XEphem.TZone: 7:00:00 XEphem*TZone.Local.set: False 24there is no DST in Arizona LN-MPIA-MAN-ICS-010 – TAN Installation and User’s Manual – Issue 4.044 67

7.3.3 Where is the LBT?

The HORIZONS web interface https://ssd.jpl.nasa.gov/horizons.cgi sets up the following geographic/geodetic parameters for an observer at the LBT [G83]:

altitude is 3182.3 m ; • latitude is 32 deg 42 min 05.3 sec N • longitude is 250 deg 06 min 37.4 sec E ; • These are actually the same coordinates one would obtain from converting the geocentric distances and angles of the MPC Obscode G83 to WGS84 geodetic coordinates. According to http://abell.as.arizona.edu/~lbtsci/scihome.html and the LBTO brochure of http://www.lbto.org/overview.html the coordinates are

altitude is 3221 m ; • latitude is 32 deg 42 min 04.71 sec N • longitude is 109 deg 53 min 20.63 sec W (equivalent to 250 deg 06 min 39.4 sec E) • According to [28] the altitude is 3192 meters. The overall differences are small: The difference of 0.6” in latitude between the sources is 2.9 10−6 × radians or 18 meters at a radius of 6370 km. The difference of 2” in longitude is 9.7 10−6 radians × or cos(32◦) 6370 km or 52 meters. ×

7.4 doxygen doxygen is obtaine from http://www.doxygen.org and compiled with tar xzf doxygen-1.8.14.src.tar.gz cd doxygen-1.8.14 mkdir build cd build cmake -G "Unix Makefiles" .. make mv bin/doxygen ~/work/bin/Linux # or wherever the PATH variable points to cd ../.. rm -rf doxygen-1.8.14* doxygen -version