casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
Entropy.h
Go to the documentation of this file.
00001 //# Entropy.h: this defines the virtual base class Entropy
00002 //# Copyright (C) 1996,1997,1998,1999,2000
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 SYNTHESIS_ENTROPY_H
00029 #define SYNTHESIS_ENTROPY_H
00030 
00031 #include <casa/aips.h>
00032 #include <lattices/Lattices/Lattice.h>
00033 #include <casa/Arrays/Matrix.h>
00034 #include <casa/Arrays/Vector.h>
00035 #include <casa/Arrays/Array.h>
00036 #include <casa/BasicSL/String.h>
00037 
00038 namespace casa { //# NAMESPACE CASA - BEGIN
00039 
00040 //forward declaration
00041 class CEMemModel;
00042 
00043 // <summary> base class for entropy functions as used by MEM
00044 // </summary>
00045 
00046 // <use visibility=export>
00047 
00048 // <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
00049 // </reviewed>
00050 
00051 // <prerequisite> 
00052 // <li> CEMemModel
00053 // </prerequisite>
00054 //
00055 // <etymology>
00056 // This class is called Entropy because it encapsulates the required
00057 // functionality of the entropy in the CE MEM algorithm
00058 // </etymology>
00059 //
00060 // <synopsis>
00061 // Provide the generic interface to entropy functions.
00062 //
00063 // We calculate entropy, gradients, and Hessians (diagonal) of the entropy.
00064 // For efficiency reasons, we cannot restrict the methods to these calculations,
00065 // but must also subsume the loops over image pixels in which they are
00066 // used.  In this way, the Entropy classes form a tight partnership with
00067 // the MemModel classes, taking over more responcibility than strict
00068 // functional encapsulation requires.
00069 // 
00070 // This class heirarchy is used by CEMemModel, which implements
00071 // the Cornwell-Evans Maximum Entropy algorithm.
00072 //
00073 // In the Entropy constructor, we create a pointer to the CEMemModel for
00074 // reference to its Mem image, prior image, and default levels.
00075 // Since each sort of Entropy is a friend of the CEMemModel, it
00076 // has access to its private data.  However, we vow here NOT to
00077 // touch it, just to look at it.  Could have done read-only access,
00078 // but too lazy.
00079 //
00080 // </synopsis>
00081 //
00082 // <example>
00083 // <srcblock>
00084 // EntropyI myEntropyEngine(myCEMemModel&);
00085 //
00086 // Float  theEntropy myEntropyEngine.getEntropy();
00087 // </srcblock> 
00088 // </example>
00089 //
00090 // <motivation>
00091 // This class is needed to encapsulate the methods of different
00092 // functional forms of the entropy, used by Maximum Entropy (MEM)
00093 // deconvolution algorithms.
00094 // </motivation>
00095 //
00096 //
00097 // <todo asof="1998/08/02">
00098 //   <li> Nothing done yet!
00099 // </todo>
00100 
00101 
00102 // virtual base class
00103 class Entropy
00104 {
00105  public:
00106   
00107   // The default constructor is good enough, does nothing.
00108   // the MemImage and Prior image are stored in the MemModel.
00109   Entropy();
00110 
00111   
00112   // A virtual destructor may be necessary for use in derived classes.
00113   virtual ~Entropy();
00114 
00115   
00116   // calculate the entropy for the whole image
00117   virtual Float formEntropy() = 0;
00118   
00119   // calculate the Gradient dot Gradient matrix
00120   virtual void formGDG(Matrix<double> & ) = 0;
00121   
00122   // calculate the Gradient dot Gradient matrix, calculate Step
00123   virtual void formGDGStep(Matrix<double> & ) = 0;
00124   
00125   // calculate Gradient dot Step
00126   virtual Double formGDS() = 0;
00127   
00128   // report the entropy type for a logging message
00129   virtual void  entropyType(String &) = 0;
00130   
00131   // set the MemModel
00132   void setMemModel(CEMemModel& mmm) { cemem_ptr = &mmm; }
00133 
00134   // infoBanner
00135   virtual void infoBanner() = 0;
00136 
00137   // infoPerIteration
00138   virtual void infoPerIteration(uInt iteration) = 0;
00139 
00140   // are there any constraints on how the Image minimum
00141   // gets relaxed?
00142   virtual Float relaxMin() = 0;
00143   
00144   // each entropy type can have its distinct convergence
00145   // criteria
00146   virtual Bool testConvergence() = 0;
00147 
00148  protected:
00149 
00150   
00151   enum GRADTYPE {H=0, C, F, J };
00152   
00153   
00154   CEMemModel *cemem_ptr;
00155   
00156   Entropy(const Entropy &);
00157 
00158   
00159 
00160 };
00161 
00162 
00163 // <summary> Thermodynamic or Information entropy used by MEM
00164 // </summary>
00165 
00166 
00167 // Thermodynamic or Information entropy
00168 class EntropyI : public Entropy
00169 {
00170 public:
00171   
00172   // This default constructor is good enough for me.
00173   EntropyI();
00174   
00175   // destructor
00176   ~EntropyI();
00177 
00178   // calculate the entropy for the whole image
00179   Float formEntropy();
00180   
00181   // calculate the Gradient dot Gradient matrix
00182   void formGDG(Matrix<Double>& );
00183   
00184   // calculate the Gradient dot Gradient matrix, calculate Step
00185   void formGDGStep(Matrix<double> & );
00186   
00187   // calculate Gradient dot Step
00188   Double formGDS();
00189   
00190   // report the entropy type for a logging message
00191   void entropyType(String & str) 
00192     { str = "entropy type I (information/thermodynamic)"; }
00193   
00194   // infoBanner
00195   void infoBanner();
00196 
00197   // infoIteration
00198   void infoPerIteration(uInt iteration);
00199 
00200   // relax image Min
00201   Float relaxMin();
00202 
00203   // each entropy type can have its distinct convergence
00204   // criteria
00205   Bool testConvergence();
00206 
00207 
00208 protected:
00209   
00210   EntropyI(const EntropyI& );
00211   EntropyI& operator=(const EntropyI& );
00212 
00213 };
00214 
00215 
00216 // <summary> Maximum Emptiness measure used by MEM
00217 // </summary>
00218 
00219 // Emptiness measure
00220 class EntropyEmptiness : public Entropy
00221 {
00222 public:
00223   
00224   // This default constructor is good enough for me.
00225   EntropyEmptiness();
00226   
00227   // destructor
00228   ~EntropyEmptiness();
00229 
00230   // calculate the entropy for the whole image
00231   Float formEntropy();
00232   
00233   // calculate the Gradient dot Gradient matrix
00234   void formGDG(Matrix<Double>& );
00235   
00236   // calculate the Gradient dot Gradient matrix, calculate Step
00237   void formGDGStep(Matrix<double> & );
00238   
00239   // calculate Gradient dot Step
00240   Double formGDS();
00241   
00242   // report the entropy type for a logging message
00243   void entropyType(String & str) 
00244     { str = "entropy type I (information/thermodynamic)"; }
00245   
00246   // infoBanner
00247   void infoBanner();
00248 
00249   // infoIteration
00250   void infoPerIteration(uInt iteration);
00251 
00252   // relax image Min
00253   Float relaxMin();
00254 
00255   // each entropy type can have its distinct convergence
00256   // criteria
00257   Bool testConvergence();
00258 
00259 
00260 protected:
00261   
00262   EntropyEmptiness(const EntropyEmptiness& );
00263   EntropyEmptiness& operator=(const EntropyEmptiness& );
00264 
00265 };
00266 
00267 
00268 
00269 
00270 
00271 
00272 } //# NAMESPACE CASA - END
00273 
00274 #endif