casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
MSUVWGenerator.h
Go to the documentation of this file.
00001 //# MSUVWGenerator.h: Generate and insert the (u, v, w)s of a MS.
00002 //# Copyright (C) 2008
00003 //# Associated Universities, Inc. Washington DC, USA.
00004 //#
00005 //# This library is free software; you can redistribute it and/or modify it
00006 //# under the terms of the GNU Library General Public License as published by
00007 //# the Free Software Foundation; either version 2 of the License, or (at your
00008 //# option) any later version.
00009 //#
00010 //# This library is distributed in the hope that it will be useful, but WITHOUT
00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00012 //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00013 //# License for more details.
00014 //#
00015 //# You should have received a copy of the GNU Library General Public License
00016 //# along with this library; if not, write to the Free Software Foundation,
00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
00018 //#
00019 //# Correspondence concerning AIPS++ should be addressed as follows:
00020 //#        Internet email: aips2-request@nrao.edu.
00021 //#        Postal address: AIPS++ Project Office
00022 //#                        National Radio Astronomy Observatory
00023 //#                        520 Edgemont Road
00024 //#                        Charlottesville, VA 22903-2475 USA
00025 //#
00026 //# $Id$
00027 //#
00028 #ifndef MS_MSUVWGENERATOR_H
00029 #define MS_MSUVWGENERATOR_H
00030 
00031 #include <casa/aips.h>
00032 #include <casa/BasicSL/String.h>
00033 #include <ms/MeasurementSets/MeasurementSet.h>
00034 #include <ms/MeasurementSets/MSColumns.h>
00035 #include <measures/Measures/MBaseline.h>
00036 
00037 // FTMachine::rotateUVW(Matrix<Double>& uvw, Vector<Double>& dphase,
00038 //                      const VisBuffer& vb)
00039 //#include <synthesis/TransformMachines/FTMachine.h>
00040 
00041 namespace casa { //# NAMESPACE CASA - BEGIN
00042 
00043 class MeasurementSet;
00044 class LogIO;
00045 
00046 // <summary>Generates and inserts the (u, v, w)s of a MS that may or may not
00047 // already have them.  Includes antenna offsets when known.</summary>
00048 // <use visibility=export>
00049 // 
00050 // <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
00051 // </reviewed>
00052 // 
00053 // <prerequisite>
00054 //   <li> <linkto class=MeasurementSet>MeasurementSet</linkto>
00055 //   <li> <linkto class=Measure>Measure</linkto>
00056 // </prerequisite>
00057 //
00058 // <etymology>
00059 // It generates a UVW column for the MS, whether or not it already has one.
00060 // It is an adaptation of alma/apps/asdm2MS/UvwCoords to work with MSes instead
00061 // of ASDMs.
00062 // </etymology>
00063 //
00064 // <synopsis>
00065 // (u, v, w)s are needed for imaging, but some data sets may not come with them
00066 // included, or the (u, v, w)s may need correction.
00067 // </synopsis>
00068 //
00069 // <motivation>
00070 // Currently (10/30/2008), ASDMs from either the ALMA Test Facility or the
00071 // EVLA do not come with (u, v, w)s, and need to be processed with the UVFIX
00072 // task in AIPS.  It would be preferable to process them entirely inside CASA.
00073 // </motivation>
00074 //
00075 // <todo asof="11/20/2008">
00076 // It requires as input the MS timeCentroids item which is an output in the
00077 // ASDM DAMs.
00078 //     - the use-case when the timeCentroid is baseline-based and or spectral
00079 //       window based.
00080 //     - correlationMode filter (hopefully handled by SDM -> MS import routines).
00081 //       direction item in the field table.
00082 // @note The current limitations are set by the status of the ASDM
00083 //     - OTF not supported due to a limitation in the model of the phase
00084 // </todo>
00085 class MSUVWGenerator
00086 {
00087 public:
00088   // Constructor 
00089   //      @param ms_ref Reference to the MS's columns.
00090   //      @post - The relative positions for all the antennas in the Antenna
00091   //              table are in bl_an_p.
00092   //            - timeRes_p has been conservatively calculated using rough
00093   //              estimates of the maximum baseline length and field of view.
00094   MSUVWGenerator(MSColumns& ms_ref, const MBaseline::Types bltype,
00095                  const Muvw::Types uvwtype);
00096 
00097   // Destructor
00098   ~MSUVWGenerator();
00099 
00100   // Determine the uvw for a single phaseDir and timeCentroid, and pair of
00101   // feeds (which may be the same).
00102   //
00103   //       @param ant1   Row number in the ANTENNA table of the 1st antenna.
00104   //       @param feed1  Row number in the FEED    table of the 1st feed.
00105   //       @param ant1   Row number in the ANTENNA table of the 2nd antenna.
00106   //       @param feed2  Row number in the FEED    table of the 2nd feed.
00107   //       @param uvw    The returned UVW coordinates.
00108   void uvw_bl(const uInt ant1, const uInt feed1,
00109               const uInt ant2, const uInt feed2, Array<Double>& uvw);
00110 
00111   // Calculate the uvws for the field IDs in flds that are not -1, and set
00112   // those phase directions according to phaseDirs.
00113   //       @param flds       A map from row numbers in the FIELD table to
00114   //                         indices in phaseDirs.  For example, if the MS has
00115   //                         5 fields, and the user wants to (re)calculate the
00116   //                         UVWs of only 0, 2, and 4, phaseDirs will have 3
00117   //                         entries and flds will be [0, -1, 1, -1, 2].  
00118   Bool make_uvws(const Vector<Int> flds);
00119 private:
00120   // Sets up the antenna positions as baselines (bl_an_p), the number of
00121   // antennas (nant_p), and timeRes_p.
00122   void fill_bl_an(Vector<MVBaseline>& bl_an_p);
00123   
00124   // Determine antUVW_p for every member of the sequence of antennas
00125   // defining a (sub)array.
00126   //     @param  timeCentroid    An epoch, the 'when' characterization.
00127   //     @param  fldID           The row number in the FIELD table which gives
00128   //                             the phase tracking center.
00129   //     @param  WSRTConvention  If true (WSRT only?), the l in the ul + vm
00130   //                             phase calculation decreases toward increasing
00131   //                             RA.  If false (VLA), it increases with
00132   //                             increasing RA.  See the code for more info.
00133   //     @note This function only calculates UVWs for a single time and a
00134   //     single phase center.  Fields can potentially have multiple phase
00135   //     directions, so be prepared to call this function from within a loop
00136   //     that also takes care of setting timeCentroid and phaseDir.
00137   //     @warning timeCentroid can be initialized like
00138   //       MEpoch timeCentroid(Quantity(<double>, "s"), MEpoch::TAI);
00139   //      but the accuracy is limited since there is no extra precision
00140   //      attribute (see Main table of MS v2).
00141   void uvw_an(const MEpoch& timeCentroid, const Int fldID,
00142               const Bool WSRTConvention=false);
00143 
00144   // (Sub-)array parameters constraining order and size of the output vector 
00145   // of UVW coords triplets.
00146   // struct ArrayParam{
00147 //   public:
00148 //     Int                   subarrayId;        // (sub)array identifier
00149 //     vector<Tag>           v_ant;             //<! sequence of antennas
00150 //     unsigned int          nrepeat;           //<! number of MS main table rows
00151 //                                           //   per antenna baseline
00152 //     Enum<CorrelationMode> e_correlationMode; //<! correlation mode (original
00153 //                                           //   mode passed through the user
00154 //                                           //   filter) (FOLLOWUP: is this needed?)
00155 //     string show(){
00156 //       ostringstream os;
00157 //       os << " nrepeat " << nrepeat;
00158 //       return os.str();
00159 //     }
00160   //};
00161 
00162   //****************** Member variables ********************************
00163 
00164   //**************** Initialized by ctor, ******************************
00165   //**************** so they should appear ******************************
00166   //**************** here in the same order ******************************
00167   //**************** as they do in the ctor. ******************************
00168 
00169   MSColumns& msc_p;  // the columns of the measurement set.
00170 
00171   // Coordinate system selectors.
00172   MBaseline::Ref bl_csys_p;
00173   Muvw::Types    uvw_csys_p;
00174   
00175   const ROMSAntennaColumns& antColumns_p;
00176 
00177   // The antenna positions of ms_p in ITRF.  It cannot be const because of the
00178   // need to update satellite positions.
00179   // antPositions_p and antOffset_p are references and must therefore be
00180   // initialized in the initialization list.
00181   const ROScalarMeasColumn<MPosition>& antPositions_p;
00182 
00183   // The offsets between the phase reference point (see feed_offsets below for
00184   // clarification) of each antenna and the closest point which is fixed
00185   // relative to the antenna position (i.e. an axis).  Since no one else has
00186   // defined it yet, I am defining it as the offset when the antenna is
00187   // pointing at zenith, oriented so that if it slewed down, it would move
00188   // toward the north.  (x, y, z) = (east, north, up).
00189   //
00190   // This appears to be a required column of the ANTENNA table in version 2.0
00191   // of the MeasurementSet definition
00192   // (http://aips2.nrao.edu/docs/notes/229/229.html), so it is assumed to be
00193   // present.  However, it is usually a set of zeroes, based on the common
00194   // belief that it is only needed for heterogeneous arrays, since the
00195   // receivers of homogeneous arrays move in concert.  That is not true when
00196   // there are independent pointing errors.
00197   const ROScalarMeasColumn<MPosition>& antOffset_p;
00198 
00199   // The position of the first antenna.
00200   MPosition refpos_p;
00201   
00202   // Ditto for feed.
00203   //const ROMSFeedColumns *feedColumns_;
00204 
00205   // The offset between the feed and the phase reference point of each antenna
00206   // in the same frame as ant_offsets.  Therefore the feed position is
00207   //  ant_positions_p(ant) + [rotation matrix](pointing) (ant_offsets_p[ant] +
00208   //                                                    feed_offsets_p[ant])
00209   const ROScalarMeasColumn<MPosition>& feedOffset_p;
00210 
00211   MBaseline::Types refposref_p;  
00212 
00213   // The antenna positions - refpos_p.getValue().
00214   Vector<MVBaseline> bl_an_p;
00215 
00216   uInt nant_p;  // # of antennas
00217 
00218   // The minimum time difference for forcing an update of the UVWs.  We're not
00219   // trying to do time averaging here, so it should be small, but not so small
00220   // that uvw_an() is called for every baseline, even when the times are
00221   // practically the same.
00222   Double timeRes_p;
00223 
00224   //************* Initialized later, if at all. ********************
00225   
00226   // Log functions and variables
00227   LogIO sink_p;
00228   LogIO& logSink() {return sink_p;}
00229 
00230   //map<Tag, ArrayParam>      m_array_p;     // FIX: Tag
00231 
00232   // The UVW "positions" of each antenna being used during a time bin,
00233   // i.e. the (u, v, w) of the baseline between antennas m and n is
00234   //  antUVW_p[n] - antUVW_p[m].
00235   // <todo asof="02/18/2009">
00236   // Generalize to multifeed systems.
00237   // </todo>
00238   Vector<Vector<Double> > antUVW_p;
00239 
00240   // the 3 fundamental attributes of the state machine
00241   Double                timeCentroid_p;
00242   ROArrayColumn<Double> phaseDir_p; 
00243   //Int                   subarrayId_p;
00244 
00245   // The number of wavelengths by which a feed may move relative to the
00246   // corresponding feed in another antenna of the array without requiring the
00247   // offset to be included in uvw calculations.  If < 0 the offset will always
00248   // be included.
00249   //
00250   // Offsets include:
00251   //    ant_offset:  OFFSET in the ANTENNA table of an MS.
00252   //                 The separation between an antenna's "phase reference
00253   //                 point" and its closest point (usu. an axis) fixed rel
00254   //                 to its position.
00255   //
00256   //    feed_offset: POSITION in the FEED table of an MS.
00257   //                 The separation between a feed and ant_pos + ant_offset.
00258   //                 Just another offset to add to ant_offset, but unlike
00259   //                 ant_offset it is likely to change when the band is
00260   //                 changed.
00261   //
00262   //    rec_offset: Not found in MSes, acc. to vers. 2 of of the MeasurementSet
00263   //                definition (http://aips2.nrao.edu/docs/notes/229/229.html).
00264   //                The separation between a receptor and its feed.
00265   //                Only needed for feed arrays.  The above URL defines a feed
00266   //                (incl. feed arrays) as a set of receptors that should be
00267   //                calibrated as a single entity.  Predicting how observers
00268   //                will decide to calibrate feed arrays is difficult,
00269   //                especially since there are no interferometers with feed
00270   //                arrays yet, but it can be argued that rec_offset can be
00271   //                ignored in many cases.  If a feed array's output is
00272   //                combined before leaving the feed (i.e. a beamforming
00273   //                array), it may as well be treated as a single feed.  If the
00274   //                receptor outputs are kept separate longer, they likely need
00275   //                to be calibrated separately and get their own FEED tables.
00276   //
00277   // They affect how the baselines of heterogeneous arrays vary with phase
00278   // tracking direction, and make the baselines of any array depend on pointing
00279   // errors.  The latter effect is often neglected, and the offsets are written
00280   // as sets of zeroes, even though they really are not.
00281   //
00282   Double offset_tolerance;
00283   
00284   // 
00285   Bool   adj_uvw_for_ptg_err;
00286 };
00287   
00288 } //# NAMESPACE CASA - END
00289 
00290 #endif