Line data    Source code

       1             : //# VisEquation.h: Interface definition for Vis Equation
       2             : //# Copyright (C) 1996,1997,1999,2000,2001,2002,2003
       3             : //# Associated Universities, Inc. Washington DC, USA.
       4             : //#
       5             : //# This library is free software; you can redistribute it and/or modify it
       6             : //# under the terms of the GNU Library General Public License as published by
       7             : //# the Free Software Foundation; either version 2 of the License, or (at your
       8             : //# option) any later version.
       9             : //#
      10             : //# This library is distributed in the hope that it will be useful, but WITHOUT
      11             : //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
      12             : //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
      13             : //# License for more details.
      14             : //#
      15             : //# You should have received a copy of the GNU Library General Public License
      16             : //# along with this library; if not, write to the Free Software Foundation,
      17             : //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
      18             : //#
      19             : //# Correspondence concerning AIPS++ should be adressed as follows:
      20             : //#        Internet email: casa-feedback@nrao.edu.
      21             : //#        Postal address: AIPS++ Project Office
      22             : //#                        National Radio Astronomy Observatory
      23             : //#                        520 Edgemont Road
      24             : //#                        Charlottesville, VA 22903-2475 USA
      25             : //#
      26             : //#
      27             : 
      28             : #ifndef SYNTHESIS_VISEQUATION_H
      29             : #define SYNTHESIS_VISEQUATION_H
      30             : 
      31             : #include <casacore/casa/aips.h>
      32             : #include <casacore/casa/BasicSL/Complex.h>
      33             : #include <casacore/casa/Arrays/Array.h>
      34             : #include <casacore/casa/Arrays/Cube.h>
      35             : #include <msvis/MSVis/VisBuffer.h>
      36             : #include <msvis/MSVis/VisBuffer2.h>
      37             : #include <synthesis/MeasurementComponents/VisCal.h>
      38             : #include <synthesis/MeasurementComponents/SolvableVisCal.h>
      39             : 
      40             : namespace casa { //# NAMESPACE CASA - BEGIN
      41             : 
      42             : // <summary> 
      43             : // Visibility Measurement Equation
      44             : // </summary>
      45             : 
      46             : // <use visibility=export>
      47             : 
      48             : // <reviewed reviewer="" date="" tests="" demos="">
      49             : 
      50             : // <prerequisite>
      51             : //   <li> <linkto module="MeasurementComponents">MeasurementComponents</linkto> module
      52             : // </prerequisite>
      53             : //
      54             : // <etymology>
      55             : // Visibility Equation describes a model for measurements from a
      56             : // generic synthesis telescope
      57             : // </etymology>
      58             : //
      59             : // <synopsis> 
      60             : // This is responsible for the Measurement Equation of the Generic
      61             : // Interferometer due to Hamaker, Bregman and Sault and later extended
      62             : // by Noordam, and Cornwell.
      63             : //
      64             : // See <linkto module="MeasurementEquations">MeasurementEquations</linkto>
      65             : // for more details of the form of the VisEquation.
      66             : //
      67             : // VisEquation provides the following:
      68             : // <ul>
      69             : // <li> Sorting of calibration terms (VisCals) in the Visibility Equation
      70             : // <li> Application of calibration terms to data (via delegation to VisCals)
      71             : // <li> Delivery of other evaluations of the VisEquation, e.g., (differentiated) residuals
      72             : // </ul>
      73             : // </synopsis> 
      74             : //
      75             : // <example>
      76             : // <srcblock>
      77             : //
      78             : // </srcblock>
      79             : // </example>
      80             : //
      81             : // <motivation>
      82             : // VisEquation is part of a framework of classes that are
      83             : // designed for synthesis calibration and imaging. The others are the 
      84             : // <linkto module=MeasurementComponents>MeasurementComponents</linkto>.
      85             : // </motivation>
      86             : //
      87             : // <todo asof="">
      88             : // </todo>
      89             : 
      90             :   class SolveDataBuffer;  // VI2
      91             : 
      92             : class VisEquation {
      93             : public:
      94             : 
      95             :   // Contructor
      96             :   VisEquation();
      97             :   
      98             :   // Copy ctor
      99             :   VisEquation(const VisEquation& other);
     100             : 
     101             :   // Destructor
     102             :   virtual ~VisEquation();
     103             :   
     104             :   // Assignment
     105             :   VisEquation& operator=(const VisEquation& other);
     106             : 
     107             :   // Arrange for apply of a VisCal list (i.e., sort them into the correct order)
     108             :   void setapply(casacore::PtrBlock<VisCal*>& vcin);
     109             : 
     110             :   // Arrange for solve of a single SolvableVisCal
     111             :   void setsolve(SolvableVisCal& svc);
     112             : 
     113             :   // Arrange a pivot point for evaluating the equation in collapseForSim
     114             :   void setPivot(VisCal::Type pivot);
     115             : 
     116             :   // Where is the pivot?
     117           0 :   VisCal::Type pivot() const { return pivot_; };
     118             : 
     119             :   // Arrange the model to use for calibration
     120             :   void setModel(const casacore::Vector<casacore::Float>& stokes);
     121             :   inline void unSetModel() { useInternalModel_=false; };
     122             : 
     123             :   // How many terms are arranged for apply?
     124           0 :   inline casacore::Int nTerms() const { return napp_; };
     125             : 
     126             :   // casacore::List the terms
     127             :   casacore::Vector<VisCal::Type> listTypes() const;
     128             :   
     129             :   // Report if spw has solutions available from all applied tables
     130             :   //  To be deprecated in favor of VBOKforCalApply
     131             :   casacore::Bool spwOK(const casacore::Int& spw);
     132             : 
     133             :   // Report if VB can be calibrated by all supplied
     134             :   //  calibration.   If not, we can't ask it to!
     135             :   // Modern replacement for spwOK(spw) which is sensitive
     136             :   //  to obs, fld, and intent, and which supports
     137             :   //  per-caltable agnosticism (see SVC::VBOKforCalApply)
     138             :   casacore::Bool VBOKforCalApply(vi::VisBuffer2& vb);
     139             : 
     140             :   // Correct in place the OBSERVED visibilities in a VisBuffer
     141             :   //  with the apply-able VisCals
     142             :   void correct(VisBuffer& vb, casacore::Bool trial=false);
     143             :   void correct2(vi::VisBuffer2& vb, casacore::Bool trial=false, casacore::Bool doWtSp=false);
     144             : 
     145             :   // Report flag-by-cal statistics
     146             :   casacore::Record actionRec();
     147             : 
     148             :   // Corrupt in place the MODEL visibilities in a VisBuffer
     149             :   //  with the apply-able VisCals
     150             :   void corrupt(VisBuffer& vb);
     151             :   void corrupt2(vi::VisBuffer2& vb);
     152             : 
     153             :   // Correct/Corrupt in place the OBSERVED/MODEL visibilities in a VisBuffer
     154             :   //  with the apply-able VisCals on either side of the SolvableVisCal
     155             :   void collapse(VisBuffer& vb);
     156             :   void collapse2(vi::VisBuffer2& vb); // VB2 version
     157             : 
     158             : 
     159             :   // This collapse avoids I/O (assumes the vb data/model are ready),
     160             :   //  and uses a generic pivot (see setPivot) rather than the svc
     161             :   //  void collapseForSim(VisBuffer& vb);
     162             :   void collapseForSim(VisBuffer& vb);
     163             : 
     164             :   // Calculate residuals 
     165             :   //   (optionally for specific chan)
     166             :   void residuals(VisBuffer& vb, 
     167             :                  casacore::Cube<casacore::Complex>& R,
     168             :                  const casacore::Int chan=-1);
     169             :   
     170             :   // Calculate residuals and differentiated residuals
     171             :   //   (optionally for specific chan)
     172             :   void diffResiduals(CalVisBuffer& cvb);
     173             :   void diffResiduals(VisBuffer& vb, 
     174             :                      casacore::Cube<casacore::Complex>& R, 
     175             :                      casacore::Array<casacore::Complex>& dR,
     176             :                      casacore::Matrix<casacore::Bool>& Rflg); 
     177             :   void diffResiduals(VisBuffer& R,
     178             :                      VisBuffer& dR0,
     179             :                      VisBuffer& dR1,
     180             :                      casacore::Matrix<casacore::Bool>& Rflg);
     181             : 
     182             :   // SolveDataBuffer version
     183             :   void differentiate(SolveDataBuffer& sdb);  // VI2
     184             : 
     185             :   // Differentiate w.r.t. MODEL Stokes Params
     186             :   //   I.e., _corrupt_ dM/d(I,Q,U,V)
     187             :   //   NB: results stored in the sdb
     188             :   void diffModelStokes(vi::VisBuffer2& vb, std::map<casacore::String,casacore::Cube<casacore::Complex> > dMdS);
     189             :   
     190             :   // Report the VisEq's state
     191             :   void state();
     192             : 
     193             :   // Set the print level
     194           2 :   inline void setPrtlev(const casacore::Int& prtlev) { prtlev_=prtlev; };
     195             :   
     196             : protected:
     197             : 
     198             :   casacore::Bool ok();
     199             : 
     200             :   // Access to the PB of apply terms 
     201           2 :   inline casacore::PtrBlock<VisCal*>& vc()  { return (*vcpb_); };
     202             : 
     203             :   // Access to SVC
     204           0 :   inline SolvableVisCal&    svc() { return *svc_; };
     205             : 
     206             :   // Detect freq dependence along the Vis Equation
     207             :   void setFreqDep();
     208             : 
     209             :   // Divide corr data by model (per correlation)
     210             :   void divideCorrByModel(vi::VisBuffer2& vb);
     211             : 
     212             :   // Divide corr data by Stokes I model 
     213             :   void divideByStokesIModel(vi::VisBuffer2& vb);
     214             : 
     215             : 
     216             : private:
     217             : 
     218             :   // Diagnostic print level access
     219           4 :   inline casacore::Int& prtlev() { return prtlev_; };
     220             : 
     221             :   // A local copy of the list of VisCal (pointers) for applying
     222             :   //  (No ownership responsibilities)
     223             :   casacore::PtrBlock<VisCal*>* vcpb_;
     224             : 
     225             :   // Number of apply VisCals in vc_
     226             :   casacore::Int napp_;
     227             : 
     228             :   // Frequency dependence indices
     229             :   casacore::Int lfd_;     // Right-most freq-dep term on LEFT  side
     230             :   casacore::Int rfd_;     // Left-most  freq-dep term on RIGHT side
     231             : 
     232             :   // Trap for frequency averaging in collapse
     233             :   casacore::Bool freqAveOK_;
     234             : 
     235             :   // VisCal with solving interface
     236             :   //  (No ownership responsibilities)
     237             :   SolvableVisCal* svc_;
     238             : 
     239             :   // The pivot point used by collapse2
     240             :   VisCal::Type pivot_;
     241             : 
     242             :   // An internal (global) point source model
     243             :   casacore::Bool useInternalModel_;
     244             :   casacore::Vector<casacore::Float> stokesModel_;
     245             : 
     246             :   // Keep count of total visibilities processed
     247             :   //  NB: this is Sum-over-spws(ncorr*nchan*nrow)
     248             :   casacore::Int nVisTotal_;
     249             : 
     250             :   // Diagnostic print level
     251             :   casacore::Int prtlev_;
     252             : 
     253             : };
     254             : 
     255             : } //# NAMESPACE CASA - END
     256             : 
     257             : #endif