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