SMA Technical Memo

SMA Technical Memo #166 (Draft)

Subject:	MIRIAD for SMA -
	A single distribution for handling data produced from generations of SMA correlators: SWARM, hybrid ASIC+SWARM, ASIC-4GHz and ASIC-2GHz
Date:	July 21, 2017^$
From:	Jun-Hui Zhao (SAO)

^$Updated from the versions since June 21, 2016

In this memo, a single distribution of the software package Miriad for handling SMA data, or Miriad-SMASD, is introduced. The distribution of Miriad-SMASD provides SMA users an off-line reduction software package in handling SMA data produced from SMA observations over the past decade and in the SMA wideband era, covering generations of SMA correlators, ASIC with 2GHz and/or 4GHz bandwidths, hybrid configurations of ASIC+SWARM, and SWARM of wideband. In the context, we describe the software architecture in details. The software package is composed of two major blocks: (1) Miriad_WB or build-smaWB for SMA wideband data and (2) regular Miriad for SMA ASIC correlator data. The second block consists of two sub-blocks build-sma2G and build-sma4G, providing SMA users offline software in the reduction of archived data produced from the ASIC correlators with single and double bands for science observations before November 15, 2014. The newly implemented and developed block build-smaWB aims at providing users advanced offline software tools in Miriad for the reduction of SMA wideband data with a large volume (> 0.1 TB/set) as well as imaging facility for spectral line and continuum sources. The architecture specially designed for the distribution of Miriad-SMASD is also able to host new blocks of software for future SMA. A package of Miriad-SMASD with the three developed blocks of code has been installed on a server at CfA, which is accesible to public.

1. Introduction -

Since the spring 2004, SMA has joined the Miriad^[1] devlopment to support SMA data reduction. Over the past decade, the SMA frontend and correlator have been upgraded in order to confront with the cutting edge technology. Three remarkable major upgrades in correlators and online software that the SMA has gone through or been going through in addition to early testing efforts are: (i) ASIC single bandwidth (2 GHz), (ii) ASIC doubled bandwidth (4 GHz) and (iii) SWARM wideband. A size of SMA data set produced from a full-observing track has been increased from ~2 GB to ~100 GB, as the SMA upgrading from the ASIC single bandwidth correlator to a hybrid correlator with ASIC doubleband and two quadrants of SWARM band at the time when this Memo is written. The data size will be doubled when the SWARM is fully implemented. The SMA will potentially expand to a wider bandwidth in the future.

The Miriad distribution of Miriad-SMASD described in this memo intends to deliver an offline software package to cover the reduction of interferometer data produced from generations of SMA correlators over the past decade as well as new hardware upgrade in the future.

Figure 1 - the software architecture of the Miriad-SMASD, consisting two major developed blocks: build-sma2G/build-sma4G and build-smaWB. The sub-blocks marked with grey characters under the developing block SWARM+ASIC in which we are implementing more features and algorithms for handling SMA wideband data. The routines developed for handling hybrid ASIC+SWARM and SWARM correlator data have been placed there.

In addition, the platform provided with Miriad-SMASD can also be used as the testing bench in the further development of new algorithms for the reduction of wideband data produced from the future SMA. The software facility provided for imaging spectral line data appears to be excellent. Implementation and development for continuum imaging are needed for wideband data. Meanwhile, Miriad supports exporting calibrated data to the CASA of the NRAO for imaging.

2. Architecture -

Figure 1 shows the software architecture of the Miriad-SMASD package. Three developed components of the software, i.e. build-sma2G, build-sma4G, and build-smaWB, have been configured into a single distribution for SMA users. The former two contain both the source and binary codes, which are needed for the reduction of historical data archived in the SMA data system. During the transition period between November 15, 2014 and November 15, 2016 before the SMA operation with SWARM-only correlator, the Miriad-SMASD is subject to frequent updating for implementing the patches and new programs to match the data produced from the hybrid configuration of ASIC and SWARM correlators. During this period, the ASIC correlator runs into a maintance issue, and the internal data structure appears to be subject to frequent changes caused by reconfiguring spectral structure in online software due to failures of ASIC crates.

2.1. ASIC 2 GHz & 4 GHz correlator

The previously developed software in the two blocks build-sma2G and build-sma4G are now configured in this distribution for the reduction of SMA data generated from ASIC correlators, corresponding to single band or 2 GHz in bandwidth and double band in 4 GHz, respectively. The block build-sma2G is imported from the Miriad 64 bits code that was integrated into the CARMA/BIMA CVS distribution, Miriad-CVS 4.0.5. The Miriad-CVS 4.0.5 package is a stable version in handling SMA data taken before November 2009, see A Step-by-Step Procedure^[2] of the reduction of spectral line data from the ASIC (2GHz) correlator. The period prior to November 2009 is referred as SMA-2G, hereafter.

The block build-sma4G is imported from the package, SMA-Miriad 1.5.1, developed for handling ASIC double band data. The header file was based on the old SMA on-line data format. This code is valid for handling SMA data taken before November 15, 2014, covering a variety of observing modes and correlator configurations, see Data Reduction Scripts^[3] for the basic observing modes. This period is, therefore, referred as SMA-4G in this memo.

Both build-sma2G and build-sma4G have kept the software architecture as that used in the Miriad_CVS distribution which was managed by the University of Maryland. The binary tree of the two blocks are generated from the classic installation of Miriad. Several minor changes have been made to match the requirements while compiling the code under the newly updated Linux OS Redhat 6.7.

2.2. SMA wideband correlator
The major block in Miriad-SMASD contains the code that are being developed for handling broadband or wideband (WB) spectral data produced from the SWARM correlator and/or the hybrid ASIC+SWARM correlator. The autogen.sh setup developed by the Radio Lab at UC Berkeley is adopted to configure the code in compiling and installation. The binary code including bin, lib, cat, doc and etc. is segregated into a specific block build-smaWB, which has been used in Miriad_WB, a CfA-wide distribution of Miriad for SMA over the past a few years. The binary tree of build-smaWB is created by the autotoolized Miriad installation, which is different as compared to the one created from the classic Miriad installation. The source codes are being implemented for handling a large volume of data in supporting wideband data reduction and imaging. The current distributed version is able to handle data produced from a hybrid ASIC+SWARM correlator up to two quadrants of SWARM spectral chunks. Meanwhile, major development for the reduction of large volume data is being considered. The developed-binary routines in build-smaWB support the reduction of SMA wideband data. Since November 15, 2014, the format has been changed in the online software in packing data collected from the SMA. This period is referred as SMA-WB which can be broken into two: 1, the transition period with a hybrid configuration of ASIC+SWARM correlator in operation, and 2, the SWARM only. See Appendix A1 for a summary of the valid periods for the generations of SMA correlator data.

2.3. Future correlator
The software architecture configured in Miriad-SMASD can be used not only for hosting the historically distributed Miriad for the reduction of older SMA data, but also for furture development in supporting reduction of SMA data as the SMA to be upgraded with new technology. An immediate consideration is the capability in the reduction of a large volume of data and wideband imaging.

2.4. Configure for other interferometer arrays
Miriad is a versatile tool for handling various interferometer array data. Specific configurations for given telescopes were supported by the relevant organizations via BIMA. For the purpose of testing and developing algorithms for the redution of SMA wideband data, the setup for JVLA has been updated since Miriad-SMA-WB 4.0.2. The setup for extending Miriad for other interferometer arrays is retained, although Miriad-SMASD is configured for supporting SMA data reduction.

3. Environment -

The current Miriad-SMASD is only supported in Linux OS Redhat 6 or CentOS 6 and higher versions. Three C-shell scripts, i.e. miriadWB.csh, miriad4G.csh and miriad2G.csh, are provided in the distribution. The script miriadWB.csh provides the environmental setting for running the specific block of code build-smaWB to reduce the SMA data produced from the SMA observations operated since November 15, 2014 with various observing modes, ASIC only, hybrid ASIC+SWARM, SWARM only and etc. The SMA data taken during this period of observations are packed into a new format by the data collecting software online.

The data taken in the period before November 15, 2014 were in the old format. To reduce the old SMA data in Miriad, one must use routines provided in either build-sma2G for single band ASIC data taken before November of 2009 or build-sma4G for the double band data taken before November 15, 2014. The scripts miriad2G.csh or miriad4G.csh can trigger an appropriate script to set environmental variables for running build-sma2G or build-sma4G, respectively. Users must be aware of what observing dates of the SMA data that they are going to reduce. Using a corresponding script provided in the Miriad-SMASD, users can set up environemental variables for the reduction of SMA data taken in the three specific periods SMA-2G, SMA-4G and SMA-WB, see Table 1 in Appendix A1.

4. Version identification -

Over the years, many Miriad versions have been distributed around; many of them have been out of date, which do not match SMA specifications. The Miriad-SMASD provides its own identifications. The subdirector 'miriad-SMASD/' containing the code in the Miriad-SMASD distribution is recommended to place under user's home director. If 'miriad-SMASD/' is located elsewhere, say '/usr/local/miriad-SMASD/', one needs to make a symbolic link:


ln -s /usr/local/miriad-SMASD ~/miriad-SMASD

One must make appropriate environmental setting for the specific Miriad-SMASD block corresponding to the SMA data produced from a given period.

4.1. Handling data from the observing period SMA-WB
For the reduction of SMA data produced in the period SMA-WB, the wideband data produced from SWARM or hybrid ASIC+SWARM correlators, the following two lines are recommended to add in user's .cshrc:


source ~/miriad-SMASD/miriadWB.csh
setenv LD_LIBRARY_PATH ~/miriad-SMASD/build-smaWB/lib

After excuting .cshrc while login in or manually, the version identification statement will be prompted on screen for example:
MIRIAD version Miriad-smaWB *.*.* loaded from miriad-SMASD ...
The version Miriad-smaWB 3.3.0 and higher has been integrated in Miriad-SMASD.

4.2. Handling data from the observing period SMA-4G
For the reduction of SMA data produced in the period SMA-4G, the double band data produced from the ASIC correlator, then the following two lines are recommended to add in user's .cshrc:


source ~/miriad-SMASD/miriad4G.csh
setenv LD_LIBRARY_PATH ~/miriad-SMASD/build-sma4G/lib

After excuting .cshrc while login in or manually, the version identification statement will be prompted on screen for example:
MIRIAD version Miriad-smaWB 1.5.1 loaded from miriad-SMASD ...

4.3. Handling data from the observing period SMA-2G
For the reduction of SMA data produced in the period SMA-2G, the single band data produced from the ASIC correlator, then the following two lines are recommended to add in user's .cshrc:


source ~/miriad-SMASD/miriad2G.csh
setenv LD_LIBRARY_PATH ~/miriad-SMASD/build-sma2G/lib

After excuting .cshrc while login in or manually, the version identification statement will be prompted on screen for example:
MIRIAD version Miriad-sma2G 4.0.5 loaded from miriad-SMASD ...

Finally, users must disable environment settings from other versions of Miriad to avoid any possible conflicts in using an appropriate Miriad for their reduction of SMA data. We note that only C-shell (csh or tcsh) scripts for the environment setting have been developed; we are also considering implementations of the corresponding Bourn-shell (sh) scripts in near future.

Appendix -

A1. Periods valid for generations of SMA correlators

We summarize the valid periods for the data produced from specific generations of SMA correlator along with their corresponding software blocks in Miriad-SMASD. Table 1 lists the period (column 1) with a designated name (column 2) for a specific SMA correlator (column 3), and the corresponding software block along with the relevant script for environmental setting (column 4) in Miriad-SMASD which can be utilized for the reduction of SMA data produced in a given period.

 
Table 1: generations of SMA correlators 
====================================================================================
Period                     name     SMA correlator         Miriad-SMASD block/script
____________________________________________________________________________________

prior to 2009-11           SMA-2G   ASIC 2 GHz bandwidth   build-sma2G/miriad2G.csh
prior to 2014-11-15        SMA-4G   ASIC 4 GHz bandwidth   build-sma4G/miriad4G.csh
2014-11-15 to 2016-11-14   SMA-WB   hybrid ASIC+SWARM      build-smaWB/miriadWB.csh
2016-11-15 -               SMA-WB   SWARM only             build-smaWB/miriadWB.csh
____________________________________________________________________________________

A2. Example of setting environmental variables

In this Appendix, a C-shell script miriadWB.csh^₤ of environmental setting for wideband data reduction provided in Miriad-SMASD is created on the basis of the product generated from autotoolized Miriad installation.

^₤ miriadWB.csh:

# -*- shell-script -*-
# Script to set up a C shell environment to use a
# Miriad installation created with the autotools build
# system. A separate script is necessary because the 
# directory structure of an autotoolized Miriad install
# is fairly different from that of a binary tree
# built with the classic build system.
#
# JHZ: 2016-06-23 for general setup for miriad-SMASD signle distribution
#

setenv LD_LIBRARY_PATH /usr/lib:/usr/local/lib:/usr/lib/X11/

#
# users must place  the package miriad-SMASD under users home director (/home/smauser);
# if miriad-SMASD is placed under somewhere else, say /usr/local, one must make a symbolic
# link to the miriad-SMASD:
# !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
# cd                                         !
# ln -s /usr/local/miriad-SMASD miriad-SMASD !
# !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
#

cd ~/miriad-SMASD 
set MIR = `pwd`
cd

# Get the pgplot definitions. 

source "$MIR/build-smaWB/lib/pgplot-miriad-remix/pgplot-config.csh"

# Constants

setenv AIPSTV "XASIN"
setenv MIRPAGER "doc"
setenv MIRDEF .

# Things that come directly from the source tree

setenv MIRNEWS "$MIR/news"
setenv MIRPROG "$MIR/src/prog"
setenv MIRSRC  "$MIR/src"
setenv MIRSUBS "$MIR/src/subs"

# Things that are built by the build system. MIRINC must
# go here because of the maxdim headers.

setenv MIRBIN  "$MIR/build-smaWB/bin"
setenv MIRLIB  "$MIR/build-smaWB/lib"
setenv MIRCAT  "$MIR/build-smaWB/share/miriad/cat"
setenv MIRINC  "$MIR/build-smaWB/include/miriad-f"
setenv MIRDOC  "$MIR/build-smaWB/share/miriad/doc"
setenv MIRPDOC "$MIRDOC/prog"
setenv MIRSDOC "$MIRDOC/subs"
setenv MIRTEL   sma

setenv LD_LIBRARY_PATH ${MIRLIB}:${LD_LIBRARY_PATH}

# FIXME? Haven't copied the code to try to add bindir to the path
# after '.' if the latter is in it.

set path = ("$MIRBIN" $path)

alias mirfind mir.find
alias mirhelp mir.help
alias mirindex mir.index
alias mirbug 'mir.bug.csh bug'
alias mirfeedback 'mir.bug.csh feedback'

# FIXME: we may want to export WIPHELP

# Import site-specific customizations. Hopefully our
# environment variables will be enough to make us 
# compatible with existing scripts, even though our
# directory structure is different than that of a 
# classic install.

Reference -

^[1]Sault, R. J., Teuben, P. J., & Wright, M. C. H. 1995, in ASP Conf. Ser. 77,
     Astronomical  Data  Analysis  Software  and  Systems  IV,  ed.  R.  A.  Shaw,
     H. E. Payne, & J. J. E. Hayes (San Francisco, CA: ASP), 433 

^[2]A Step-by-Step Procedure -
    https://www.cfa.harvard.edu/sma/miriad/miriad4sma/stepbystep.html

^[3]Data Reduction Scripts -
    https://www.cfa.harvard.edu/sma/miriad/spec/SMAscripts/