casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
HogbomCleanModel.h
Go to the documentation of this file.
00001 //# HogbomCleanModel.h: this defines HogbomCleanModel
00002 //# Copyright (C) 1996,1999
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 //#
00027 //# $Id$
00028 
00029 #ifndef SYNTHESIS_HOGBOMCLEANMODEL_H
00030 #define SYNTHESIS_HOGBOMCLEANMODEL_H
00031 
00032 
00033 #include <casa/aips.h>
00034 #include <synthesis/MeasurementEquations/ArrayModel.h>
00035 #include <synthesis/MeasurementEquations/Iterate.h>
00036 #include <synthesis/MeasurementEquations/ResidualEquation.h>
00037 #include <synthesis/MeasurementEquations/ConvolutionEquation.h>
00038 
00039 namespace casa { //# NAMESPACE CASA - BEGIN
00040 
00041 // <summary>
00042 // A Class for performing Hogbom Clean's of Arrays
00043 // </summary>
00044 
00045 // <use visibility=export>
00046 
00047 // <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
00048 // </reviewed>
00049 
00050 // <prerequisite> 
00051 // <li> ResidualEquation/ConvolutionEquation 
00052 // <li> LinearModel/LinearEquation Paradigm 
00053 // </prerequisite>
00054 //
00055 // <etymology>
00056 // This class is called HogbomCleanModel because thats the algorithm it uses
00057 // deconvolve the model. 
00058 // </etymology>
00059 //
00060 // <synopsis>
00061 // This class is used to perform the Hogbom Clean Algorithm on an
00062 // Array. Only the deconvolved model of the sky are directly stored by this
00063 // class. The point spread function (psf) and convolved (dirty) image are
00064 // stored in a companion class which is must be derived from
00065 // ResidualEquation. 
00066 // 
00067 // The cleaning works like this. The user constructs a HogbomCleanModel by
00068 // specifying an initial model of the sky. This can by be
00069 // one,two,three... dimensional depending on the dimension of the psf (see
00070 // below). The user then constructs a class which implements the forward
00071 // equation between the model and the dirty image. Typically this will be
00072 // the ConvolutionEquation class, although any class which has a
00073 // ResidualEquation interface will be work (but perhaps very slowly, as the
00074 // ConvolutionEquation class has member functions optimised for cleaning)
00075 //
00076 // The user then calls the solve() function (with the appropriate equation
00077 // class as an arguement), and this class will perform the Hogbom clean.
00078 // The various clean parameters are set (prior to calling solve) using the
00079 // functions derived from the Iterate class, in particular setGain(),
00080 // setNumberIterations() & setThreshold() (to set a flux limit). 
00081 // 
00082 // The solve() function does not return either the deconvolved model or the
00083 // residuals. The solved model can be obtained using the getModel() function
00084 // (derived from ArrayModel()) and the residual can be obtained using the
00085 // residual() member function of the Convolution/Residual Equation Class.
00086 // 
00087 // The size and shape of the model used in this class MUST be the same as
00088 // the convolved data (Dirty Image), stored in the companion
00089 // ResidualEquation Class. However the model (and convolved data) can have
00090 // more dimensions than the psf, as well as a different size (either larger
00091 // or smaller). When the dimensionality is different the cleaning is done
00092 // independendtly in each "plane" of the model. (Note this has not
00093 // been implemented yet but is relatively simple to do if necessary). 
00094 //
00095 // This multi-dimensionalty is exploited when cleaning arrays of
00096 // StokesVectors. Here the Array of StokesVectors is decomposed into a stack
00097 // of 4 Floating point arrays and the cleaning is done on all the the arrays
00098 // simultaneosly. The criterion for choosing the brightest pixel has been
00099 // generalised by using the "length" of the Stokesvector in 4 dimensional
00100 // space. 
00101 //
00102 // A companion class to this one is MaskedHogbomCleanModel. This provides
00103 // the same functionality but is used with MaskedArrays which indicate which
00104 // regions of the model to search for clean components. 
00105 //
00106 // </synopsis>
00107 //
00108 // <example>
00109 // <srcblock>
00110 // Matrix<Float> psf(12,12), dirty(10,10), initialModel(10,10);
00111 // ...put appropriate values into psf, dirty, & initialModel....
00112 // HogbomCleanModel<Float> deconvolvedModel(initialModel); 
00113 // ConvolutionEquation convEqn(psf, dirty);
00114 // deconvolvedModel.setGain(0.2); 
00115 // deconvolvedModel.setNumberIterations(1000);
00116 // Bool convWorked = deconvolvedModel.solve(convEqn);
00117 // Array<Float> finalModel, residuals;
00118 // if (convWorked){
00119 //   finalModel = deconvolvedModel.getModel();
00120 //   ConvEqn.residual(deconvolvedModel, finalResidual);
00121 // }
00122 // </srcblock> 
00123 // </example>
00124 //
00125 // <motivation>
00126 // This class is needed to deconvolve images.
00127 // </motivation>
00128 //
00129 // <templating arg=T>
00130 // I have tested this class with Arrays of
00131 //    <li> Float
00132 //    <li> StokesVector
00133 // </templating>
00134 //
00135 // <todo asof="1996/05/02">
00136 //   <li> Make changes so that multidimensions work as advertised
00137 //   <li> compare timing with other clean implementations (ie, Mark's
00138 //   CleanTools, SDE, AIPS & miriad) 
00139 // </todo>
00140 
00141 template<class T> class HogbomCleanModel: 
00142   public ArrayModel<T>,
00143   public Iterate
00144 {
00145 public:
00146   // The default constructor does nothing more than initialise a zero length
00147   // array to hold the deconvolved model. If this constructor is used then 
00148   // the actual model must be set using the setModel() function of the
00149   // ArrayModel class.
00150   HogbomCleanModel():ArrayModel<T>(){};
00151   // Construct the HogbomCleanModel object and initialise the model.
00152   HogbomCleanModel(const Array<T> & model):ArrayModel<T>(model){};
00153   // Using a Hogbom clean deconvolution proceedure solve for an improved
00154   // estimate of the deconvolved object. The convolution/residual equation
00155   // contains the psf and dirty image. When called with a ResidualEquation
00156   // arguement a quite general interface is used that is slow. The
00157   // convolution equation contains functions that speed things up. The
00158   // functions return False if the deconvolution could not be done.
00159   // <group>
00160   Bool solve(ResidualEquation<Array<T> > & eqn);
00161   Bool solve(ConvolutionEquation & eqn);
00162   // </group>
00163 
00164   //# Make parent members known.
00165 protected:
00166   using ArrayModel<T>::theModel;
00167 };
00168 
00169 
00170 } //# NAMESPACE CASA - END
00171 
00172 #ifndef AIPS_NO_TEMPLATE_SRC
00173 #include <synthesis/MeasurementEquations/HogbomCleanModel.tcc>
00174 #endif //# AIPS_NO_TEMPLATE_SRC
00175 #endif