SkyJones.h

Go to the documentation of this file.
00001 //# SkyJones.h: Definitions of interface for SkyJones 
00002 //# Copyright (C) 1996,1997,1998,2000,2003
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 adressed 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 //#
00027 //# $Id$
00028 
00029 #ifndef SYNTHESIS_SKYJONES_H
00030 #define SYNTHESIS_SKYJONES_H
00031 
00032 #include <casa/aips.h>
00033 #include <casa/BasicSL/Complex.h>
00034 #include <msvis/MSVis/VisSet.h>
00035 #include <images/Images/ImageInterface.h>
00036 #include <components/ComponentModels/ComponentList.h>
00037 #include <components/ComponentModels/SkyComponent.h>
00038 #include <casa/Utilities/CompositeNumber.h>
00039 
00040 namespace casa { //# NAMESPACE CASA - BEGIN
00041 
00042 //#forward
00043 class ImageRegion;
00044 class CoordinateSystem;
00045 class SkyEquation;
00046 
00047 //# Need forward declaration for Solve in the Jones Matrices
00048 
00049 // <summary> 
00050 // Sky Jones: Model sky-plane instrumental effects for the SkyEquation
00051 // </summary>
00052 
00053 // <use visibility=export>
00054 
00055 // <reviewed reviewer="" date="" tests="" demos="">
00056 
00057 // <prerequisite>
00058 // <li> <linkto class="SkyEquation">SkyEquation</linkto> class
00059 // </prerequisite>
00060 //
00061 // <etymology>
00062 // SkyJones describes an interface for Components to be used in
00063 // the <linkto class="SkyEquation">SkyEquation</linkto>.
00064 // It is an Abstract Base Class: most methods
00065 // must be defined in derived classes.
00066 // </etymology>
00067 //
00068 // <synopsis> 
00069 //
00070 // A SkyJones implements the instrumental effect of some sky-plane based
00071 // calibration effect. It conceptually applies an image of Jones matrices
00072 // to an image. For example, it takes an image of the sky brightness and
00073 // applies the complex primary beam for a given interferometer. Only the
00074 // interface is defined here in the Abstract Base Class. Actual concrete
00075 // classes must be derived from SkyJones.  Some (most) SkyJones are
00076 // solvable: the SkyEquation can be used by the SkyJones to return
00077 // gradients with respect to itself (via the image interface). Thus for a
00078 // SkyJones to solve for itself, it calls the SkyEquation methods to get
00079 // gradients of chi-squared with respect to the image pixel values. The
00080 // SkyJones then uses these gradients as appropriate to update itself.
00081 //
00082 //
00083 // The following examples illustrate how a SkyJones can  be
00084 // used:
00085 // <ul>
00086 // <li> Mosaicing: one SkyJones for the primary beam. For efficiency
00087 // the image must be cached and the VisSet iteration order set to
00088 // minimize the number of recalculations.
00089 // </ul>
00090 // </synopsis> 
00091 //
00092 // <example>
00093 // <srcblock>
00094 //
00095 //  // Low level code example:
00096 //
00097 //    MeasurementSet ms("imagertest/3C273XC1.ms", Table::Update);
00098 //    VPSkyJones  unsquintedVPSJ(ms);
00099 //    VPSkyJones  squintedVPSJ(ms, True, Quantity(5.0, "deg"), BeamSquint::GOFIGURE);
00100 //    unsquintedVPSJ.reset();
00101 //    squintedVPSJ.reset();
00102 //
00103 //    PagedImage<Complex> imageIn;
00104 //    PagedImage<Complex> imageOut;  // in reality, this ouwld need more construction with coords and shapes
00105 //
00106 //    VisSet vs(ms,bi,chanSelection,interval);
00107 //
00108 //    Int row = 0;
00109 //    VisIter &vi = vs.iter();
00110 //    VisBuffer vb(vi);
00111 //    for (vi.originChunks();vi.moreChunks();vi.nextChunk()) {
00112 //      cout << "This is integration: " << nChunks++ << endl;
00113 //      for (vi.origin();vi.more();vi++) {
00114 //        if (myVPSJ.change(vb)) { 
00115 //          cout << "State has changed: " << endl;
00116 //          squintedVPSJ.showState(os);
00117 //          squintedVPSJ.apply(imageIn, imageOut, vb, row);
00118 //        }
00119 //      }
00120 //    }
00121 //
00122 //
00123 //      // High Level Code Example:
00124 //
00125 //
00126 //      // Create an ImageSkyJones from an image on disk
00127 //      ImageSkyModel ism(PagedImage<Float>("3C273XC1.modelImage"));
00128 //
00129 //      // Make an FTMachine: here we use a simple Grid and FT.
00130 //      GridFT ft;
00131 //
00132 //      SkyEquation se(ism, vs, ft);
00133 //
00134 //      // Make a Primary Beam Sky Model
00135 //      VPSkyJones pbsj(ms);
00136 //
00137 //      // Add it to the SkyEquation
00138 //      se.setSkyJones(pbsj);
00139 //
00140 //      // Predict the visibility set
00141 //      se.predict();
00142 //
00143 //      // Read some other data
00144 //      VisSet othervs("3c84.MS.Otherdata");
00145 //
00146 //      // Make a Clean Image and write it out
00147 //      HogbomCleanImageSkyJones csm(ism);
00148 //      if (csm.solve(othervs)) {
00149 //        PagedImage<Float> cleanImage=csm.image(0);
00150 //        cleanImage.setName("3c84.cleanImage");
00151 //      }
00152 //
00153 // </srcblock>
00154 // </example>
00155 //
00156 // <motivation>
00157 // The properties of sky-plane based calibration effects must be described
00158 // for the <linkto class="SkyEquation">SkyEquation</linkto>
00159 // </motivation>
00160 //
00161 // <todo asof="97/10/01">
00162 // <li> There are no Concrete Classes derived from SkyJones!
00163 // <li> Solvable part needs implementation: we need to derive an
00164 // image of gradients of the elements of the Jones matrix. See VisJones
00165 // for how to do this.
00166 // </todo>
00167 
00168 class SkyJones {
00169 public:
00170  
00171   // Allowed types of VisJones matrices
00172   enum Type{E,T,F,D};
00173 
00174   enum SizeType{COMPOSITE, POWEROF2, ANY};
00175 
00176   SkyJones();
00177   // Destructor.
00178   virtual ~SkyJones();
00179 
00180   // Apply Jones matrix to an image (and adjoint)
00181   // <group>
00182   virtual ImageInterface<Complex>& apply(const ImageInterface<Complex>& in,
00183                                          ImageInterface<Complex>& out,
00184                                          const VisBuffer& vb, Int row,
00185                                          Bool forward=True) = 0;
00186 
00187   virtual ImageInterface<Float>& apply(const ImageInterface<Float>& in,
00188                                          ImageInterface<Float>& out,
00189                                          const VisBuffer& vb, Int row) = 0;
00190 
00191   virtual ImageInterface<Float>& applySquare(const ImageInterface<Float>& in,
00192                                              ImageInterface<Float>& out,
00193                                              const VisBuffer& vb, Int row) = 0;
00194   // </group>
00195 
00196   // Apply Jones matrix to a sky component (and adjoint)
00197   // <group>
00198   virtual SkyComponent& apply(SkyComponent& in,
00199                               SkyComponent& out,
00200                               const VisBuffer& vb, Int row, Bool forward=True) = 0;
00201   virtual SkyComponent& applySquare(SkyComponent& in,
00202                                     SkyComponent& out,
00203                                     const VisBuffer& vb, Int row) = 0;
00204   // </group>
00205 
00206   // Has this operator changed since the last application?
00207   virtual Bool changed(const VisBuffer& vb, Int row) = 0;
00208 
00209   // Does this operator changed in this VisBuffer,
00210   // starting with row1?
00211   // If yes, we return in row2, the last row that has the
00212   // same SkyJones as row1.
00213   virtual Bool changedBuffer(const VisBuffer& vb, Int row1, Int& row2) = 0;
00214 
00215   // Reset
00216   virtual void reset() = 0;
00217 
00218   // Assure
00219   virtual void assure(const VisBuffer& vb, Int row) = 0;
00220 
00221   // Does the operator change in this visbuffer or since the last
00222   // call?       
00223   // I'm not sure this is useful -- come back to it
00224   // m.a.h.  Dec 30 1999
00225   virtual Bool change(const VisBuffer& vb) = 0;
00226 
00227   // Return the type of this Jones matrix (actual type of derived class).
00228   virtual Type type() = 0;
00229 
00230   // Apply gradient
00231   virtual ImageInterface<Complex>& 
00232   applyGradient(ImageInterface<Complex>& result, const VisBuffer& vb, Int row)
00233   = 0;
00234   virtual SkyComponent&
00235   applyGradient(SkyComponent& result, const VisBuffer& vb, Int row)
00236   = 0;
00237 
00238   // Is this solveable?
00239   virtual Bool isSolveable()=0;
00240 
00241   // Initialize for gradient search
00242   virtual void initializeGradients()=0;
00243 
00244   // Finalize for gradient search
00245   virtual void finalizeGradients()=0;
00246  
00247   // Add to Gradient Chisq
00248   virtual void addGradients(const VisBuffer& vb, Int row, const Float sumwt, 
00249                             const Float chisq, const Matrix<Complex>& c, 
00250                             const Matrix<Float>& f)=0;
00251  
00252   // Solve
00253   virtual Bool solve (SkyEquation& se) = 0;
00254 
00255   // Get the ImageRegion of the primary beam on an Image for a given pointing
00256   // Note: ImageRegion is not necesarily constrained to lie within the
00257   // image region (for example, if the pointing center is near the edge of the
00258   // image).  fPad: extra fractional padding beyond the primary beam support
00259   // (note: we do not properly treat squint yet, this will cover it for now)
00260   // iChan: frequency channel to take: lowest frequency channel is safe for all
00261   // SizeType: COMPOSITE = next larger composite number,
00262   //           POWEROF2  = next larger power of 2,
00263   //           ANY       = just take what we get!
00264   //
00265   // Potential problem: this ImageRegion includes all Stokes and Frequency Channels
00266   // present in the input image.
00267 
00268   virtual ImageRegion*  extent (const ImageInterface<Complex>& im, 
00269                                 const VisBuffer& vb, 
00270                                 const Int irow=-1,                        
00271                                 const Float fPad=1.2,  
00272                                 const Int iChan=0, 
00273                                 const SkyJones::SizeType sizeType=COMPOSITE)=0;
00274   virtual ImageRegion*  extent (const ImageInterface<Float>& im, 
00275                                 const VisBuffer& vb,  
00276                                 const Int irow=-1,
00277                                 const Float fPad=1.2,  
00278                                 const Int iChan=0, 
00279                                 const SkyJones::SizeType sizeType=COMPOSITE)=0;
00280 
00281   virtual String telescope()=0;
00282   
00283   virtual Int support(const VisBuffer& vb, const CoordinateSystem& cs)=0;
00284 
00285   virtual void setThreshold(const Float t){threshold_p=t;};
00286   virtual Float threshold(){return  threshold_p;};
00287 
00288 
00289 protected:
00290 
00291   // Could be over-ridden if necessary
00292   virtual String typeName() {
00293     switch(type()) {
00294     case SkyJones::E:    // voltage pattern (ie, on-axis terms)
00295       return "E Jones";
00296     case SkyJones::T:    // Tropospheric effects
00297       return "T Jones";
00298     case SkyJones::F:    // Faraday
00299       return "F Jones";
00300     case SkyJones::D:    // D Beam (ie, polarization leakage beam; off axis terms)
00301       return "D Jones";
00302     }
00303     return "Not known";
00304   };
00305 
00306   Float threshold_p;
00307  
00308 
00309 private:    
00310 };
00311  
00312 
00313 } //# NAMESPACE CASA - END
00314 
00315 #endif
00316 
00317 
00318 
00319 
00320 
00321 
00322 
00323 
00324 
00325 
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1