This page documents work on converting GBT sdfits file to the format used by the ACSIS gridder. The ACSIS gridder is an application in starlink.

Relevant documentation:

  • Note: This works for Red Hat Enterprise Linux 4. There is a README file in the top-level starbuild directory that is helpful. Note especially that if gcc4.x is used then gfortran can not be used and g95 should be used (not tried personally).
  • Built in my (bgarwood) home directory in CV: /users/bgarwood/starlink; installed in /users/bgarwood/star/
  • svn checkout starbuild
  • cd starbuild
  • export FC=g77
  • export F77=g77
  • export STARCONF_DEFAULT_PREFIX=/users/bgarwood/star
  • export STARCONF_DEFAULT_STARLINK=/users/bgarwood/star
  • ensure that the installed bin and installed buildsupport are in $PATH
    • export PATH=/users/bgarwood/star/bin:/users/bgarwood/star/buildsupport:$PATH
  • ./bootstrap
  • make configure-deps
  • ./configure -C
  • make world

Usage notes and tools:

  • setting environment (STARLINK_DIR is the installed directory = /users/bgarwood/star)
    • bash-shell
      • source $STARLINK_DIR/etc/profile
    • c-shell
      • source $STARLINK_DIR/etc/login
      • source $STARLINK_DIR/etc/cshrc
  • "smurf" is the application that will be eventually used (converting data and making an image)
    • smurfhelp makecube
    • it appears that you have to type "smurf" to set things necessary for smurf utilities to be available
  • "gaia" should be available at this point
  • KAPPA manual: showme sun95 (it's huge - over 600 pages)
  • Tools for browsing NDF files (format that ACSIS format is built on)
    • ndftrace - summaries. Use "fullframe" option to give detailed world coordinate system information.
    • hdstrace - lower level view of the file contents
    • gaia can be used to view these data files
    • visually browse data
      • included as part of "humu" binary distribution (can be downloaded at above link). Copy the starjava directory into the build tree (/users/bgarwood/star) to get access to "treeview".

Conversion tool design

  • Similar to existing idlToSdfits utility used to convert sdfits to classic AIPS.
    • The output data file is written once - it can not be appended to.
    • The data all come from the same set of samplers.
    • The data are intended to be mapped together, although makecube allows selection essentially by sampler as well as by velocity range.
    • I think the following are likely to be true, although I may reach a different conclusion when I get to that point:
      • Any necessary regridding to the same frequency axis should occur before the data are written to the output file. This may either happen as the sdfits file to be converted is written or it could happen in this conversion tool.
      • The frequency/velocity frame in the output file should all reference the same reference frame (same epoch and pointing direction), which is probably the desired center of the image. That may require some adjustments by this conversion function.
  • All of the conversion tool is designed to organize the data so that the existing libacsis function, acsSpecWriteTS can be called. Apart from the array of data values to be written, that consists of filling the values into two structures: JCMState, and ACSISSpecHdr. Those structures cover the meta information described in the ACSIS Format Interface Control Document.
  • I think WCS information is set in a separate call, but I haven't sorted that out yet.

arguments to acsSpecOpenTS

This function is called in creating the file. These arguments determine the name and some of the fixed aspects of the data structure (sizes, receptor names, etc). In this table file indicates what this is related to in the output file.

argument type Def file sdfits units
dir const char * filename prefix? filename prefix? "g"  
yyyymmdd unsigned int output filename body output filename body First DATEOBS in file, truncated to just the date  
obsnum unsigned int ?? ?? SCAN??  
nrecep unsigned int number of receptors 2nd dim of DATA, length of RECEPTORS in ACSIS structure number of unique SAMPLERS  
nsubsys unsigned int number of subsystems "number of subbands in your correlator" - TimJ, e-mail number of unique IFs  
recepnames const char * receptor names RECEPTORS in ACSIS Unique names of SAMPLERS  
focal_station const char * focal station FOCAL_STATION in ACSIS ??  
fplanex const float [] arc offset in X, Y of FPLANEX BEAMXELOFF radians
fplaney const float [] each receptor FPLANEY BEAMELOFF radians
ocsonfig const char * XML configuration MORE/JCMTOS/CONFIG unavailable in sdfits radians
status int * returned value      

arguments to acsSpecWriteTS

argument type Def sdfits
subsys unsigned int subsystem number equivalent to IFNUM in GBTIDL?
nchans unsigned int number of channels First element of TDIMa
spectrum[] const float this spectrum DATA
record const JCMTState * The JCMTState structure appropriate for this spectrum See below
spechdr const ACSISSpecHdr * The ACSISSpecHdr structure appropriate for this spectrum See below
status int * returned value  

arguments to acsSpecCloseTS

argument type Def file sdfits
fits[] const AstFitsChan * ?? ? ??
incArchiveBounds int ?? ?? ??
status int * returned value  

ACSISSpecHdr structure

This structure is used to fill in the values for the ACSIS meta data in the file. I think "feed" here is synonymous with "receptor". I think for the GBT it's equivalent to SAMPLER. The mapping here assumes that the positions are in the AZEL coordinate as opposed to the tracking coordinate. The RECEPPOS_SYS field in this structure in the file should be "AZEL", but I don't know yet how that's set. The positions are true angular offsets not just simple differences in coordinates. In this table file indicates what this is related to in the output file.

field type Def file SDFITS units
rts_endnum int Highest number expected in this sequence ? ?Highest rts_num expected? NROWS?  
acs_feedx double X coord of feed "acs_feed" RECEPPOS 0.0 radians
acs_feedy double Y coord of feed "acs_feed" RECEPPOS 0.0 radians
acs_feed unsigned int feed number index into "RECEPTORS" for this receptor index into "RECEPTORS" for this sampler  
acs_tsys float Tsys TSYS TSYS K
acs_trx float Trx TRX 0.0 K

JCMState structure

field typeSorted ascending Def sdfits units
tcs_tr_ac[1,2] actual telescope coordinates in the TRACKING frame CRVAL2, CRVAL3 radians
tcs_tr_bc[1,2] bsae telescope coordinate in the TRACKING frame ?? radians
smu_chop_phase char[1] Chap phase (A, B, or M) "M"  
tcs_beam char[1] telescope nod position (A,B, or M) "M"  
tcs_tr_sys char[16] Name of tracking coordinate frame (AZEL, J2000, etc) Use CTYPE2 and CTYPE3 ala GBTIDL  
acs_source_ro char[16] Core description of the spectrum data ?SOURCE?  
tcs_source char[32] label of the base position, usually "SCIENCE" or "REFERENCE"    
rts_tasks char[80] tasks in involved in the sequence    
tcs_tr_dc[1,2] demanded telescope coordinates in the TRACKING frame ?? radians
rts_end double MJD TAI of end of sequence step DATE-OBS + DURATION converted to MJD TAI MJD TAI
smu_[x,y,z] double SMU focus position from nominal 0.0  
smu_az_jig_[x,y] double SMU jiggle position in AZEL coords 0.0 arcsec
smu_az_chop_[x,y] double SMU chop position in AZEL coords 0.0 arcsec
smu_tr_jig_[x,y] double SMU jiggle position in tracking coords 0.0 arcsec
smu_tr_chop_[x,y] double SMU chop position in tracking coords 0.0 arcsec
tcs_tai double TAI time used to determine TCS values - time used to determine TCS values DATE-OBS converted to TAI TAI MJD?
tcs_airmass double Airmass of the telescope tracking centre sec(90-ELEVATIO)  
tcs_az_ang double Angle between PA=0 in the focal plane and PA=0 in AZEL 0.0 ? radians
tcs_az_ac[1,2] double Actual coordinates of the telescope in AZEL AZIMUTH,ELEVATIO radians
tcs_az_dc[1,2] double Demanded coordinates of the telescope in AZEL ?? radians
tcs_az_bc[1,2] double Coordinates of the base position (radians) in AZEL ?? radians
tcs_tr_ang double angle between focal plane PA=0 and PA=0 in the tracking coord. frame ??  
sc2_heat double ? ? ?
pol_ang double Angle of the polarimeter waveplate 0.0  
fe_lofreq double The LO frequency used by the frontend unavailable, 0.0  
fe_doppler double The doppler correction ?related to VFRAME? ?
enviro_rel_hum float relative humidity HUMIDITY*100 %
enviro_pressure float atmospheric pressure PRESSURE ??
enviro_air_temp float Air temperature TAMBIENT K
wvm_th float ? ? ?
wvm_t12 float ? ? ?
wvm_t42 float ? ? ?
wvm_t78 float ? ? ?
wvm_tw float ? ? ?
wvm_time float ? ? ?
acs_exposure float Total on-source integration time for this spectrum EXPOSURE seconds
acs_offexposure float Total off integration time for this spectrum not available, probably EXPOSURE seconds
fts_pos float ? ? ?
smu_jig_index int Current jiggle position 0  
tcs_index int index into the observing area, usually row number or grid offset ??  
jos_dcrcontrol int DR control flag 0  
wvm_qual int ? ? ?
acs_no_prev_ref int deprecated 0  
acs_no_next_ref int deprecated 0  
acs_no_ons int deprecated 0  
rts_num unsigned int RTS sequence number to uniquely ID this information SDFITS row number 1-relative?

Adding the new command in - infrastructure basics

  • None of this has been committed to the starlink distribution yet.
  • Modeled on gsd2acsis conversion
  • New command will be called "gbt2acsis"
  • New subdirectory applications/smurf/libgbt
  • Modified files:
    • smurf_mon.c - new "GBT2ACSIS" task and call to smurf_gbt2acsis to invoke it
    • - new gbt2acsis action and parameter description
    • - add new libgbt/Makefile to AC_CONFIG_FILES
    • -add libgbt to SUBDIRS, add gbt2acsis to smurf_mon_TASKS, add to smurf_mon_LDADD
    • libsmurf/ - add smurf_gbt2acsis.c
  • New files:
    • libgbt/
    • libgbt/gbt.h
    • libgbt/gbt_wrtData.c
    • libsmurf/smurf_gbt2acsis.c - this is the main routine invoked by gbt2acsis. It eventually calls the necessary functions in libgbt to do the conversion.
    • more will certainly follow - the above is just enough get things started * I had trouble getting the build system to recognize the above. It's possible if I'd gone straight back to the ./bootstrap phase as ultimately recommended, it would have gone smoothly. In the end, I had to make copies of the new and modified files and checkout a new copy of starlink and start the build process from scratch after putting in the modified and new files into this new copy.

-- BobGarwood - 10 Mar 2008
Topic revision: r7 - 2008-04-16, BobGarwood
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding NRAO Public Wiki? Send feedback