casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
SkyCompBase.h
Go to the documentation of this file.
00001 //# SkyCompBase.h: Base class for model components of the sky brightness
00002 //# Copyright (C) 1996,1997,1998,1999,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 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: SkyCompBase.h 18093 2004-11-30 17:51:10Z ddebonis $
00028 
00029 #ifndef COMPONENTS_SKYCOMPBASE_H
00030 #define COMPONENTS_SKYCOMPBASE_H
00031 
00032 #include <casa/aips.h>
00033 #include <components/ComponentModels/ComponentType.h>
00034 #include <casa/Utilities/RecordTransformable.h>
00035 #include <casa/BasicSL/Complexfwd.h>
00036 
00037 namespace casa { //# NAMESPACE CASA - BEGIN
00038 
00039 class MFrequency;
00040 class MVFrequency;
00041 class MDirection;
00042 class MVDirection;
00043 class MVAngle;
00044 class RecordInterface;
00045 class String;
00046 class ComponentShape;
00047 class SpectralModel;
00048 class Unit;
00049 template <class T> class Flux;
00050 template <class T> class Vector;
00051 template <class T> class Matrix;
00052 template <class T> class Cube;
00053 template <class Ms> class MeasRef;
00054 
00055 // <summary>Base class for model components of the sky brightness</summary>
00056 
00057 // <use visibility=export>
00058 // <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
00059 // </reviewed>
00060 
00061 // <prerequisite> 
00062 // <li> <linkto class=Flux>Flux</linkto>
00063 // <li> <linkto class=ComponentShape>ComponentShape</linkto>
00064 // <li> <linkto class=SpectralModel>SpectralModel</linkto>
00065 // </prerequisite>
00066 //
00067 
00068 // <synopsis> 
00069 // This abstract base class defines the interface for classes that model the
00070 // sky brightness.
00071 
00072 // A model of the sky brightness is defined by three properties.
00073 // <dl>
00074 // <dt><em>A Flux</em>
00075 // <dd> This is the integrated brightness of the component.
00076 // <dt><em>A Shape</em>
00077 // <dd> This defines how the sky brightness varies as a function of position on
00078 //      the sky. Currently two shapes are supported, 
00079 //      <linkto class=PointShape>points</linkto> and
00080 //      <linkto class=GaussianShape>Gaussians</linkto>.
00081 // <dt><em>A Spectrum</em>
00082 // <dd> This defines how the component flux varies as a function of frequency.
00083 //      Currently two spectral models are supported. The simplest assumes the
00084 //      spectrum is <linkto class=ConstantSpectrum>constant</linkto> with 
00085 //      frequency. Alternatively a 
00086 //      <linkto class=SpectralIndex>spectral index</linkto> model can be used. 
00087 // </dl>
00088 
00089 // These three properties of a component can be obtained using the
00090 // <src>flux</src>, <src>shape</src> or <src>spectrum</src> functions defined
00091 // in this interface. Each of these properties is represented by an object that
00092 // contains functions for manipulating the parameters associated with that
00093 // property. eg. to set the direction of the component you would use:
00094 // <srcblock> SkyComponent comp; comp.shape().setRefDirection(newDirection);
00095 // </srcblock> See the <linkto class=Flux>Flux</linkto>, 
00096 // <linkto class=ComponentShape>ComponentShape</linkto> or 
00097 // <linkto class=SpectralModel>SpectralModel</linkto> classes for more
00098 // information on these properties and how to manipulate them.
00099 
00100 // Besides these three properties the <src>label</src> functions are provided
00101 // to associate a text string with the component.
00102 
00103 // A model of the sky brightness is by itself not very useful unless you can do
00104 // something with it. This class contains functions for deriving information
00105 // from the components. These functions are:
00106 // <dl>
00107 // <dt><src>sample</src>
00108 // <dd> This function will return the the flux in an specified pixel, at a
00109 //      specified direction at a specified frequency.
00110 // <dt><src>project</src>
00111 // <dd> This function will generate an image of the component, given a user
00112 //      specified ImageInterface object.
00113 // <dt><src>visibility</src>
00114 // <dd> This function will return the visibility (spatial coherence) that would
00115 //      be measured if the component was at the field centre of an
00116 //      interferometer with a specified (u,v,w) coordinates and observation
00117 //      frequency. 
00118 // </dl>
00119 
00120 // The <src>toRecord</src> & <src>fromRecord</src> functions are used to
00121 // convert between a SkyCompBase object and a record representation. This is
00122 // primarily so that a component can be represented in Glish. 
00123 
00124 // </synopsis>
00125 
00126 // <example>
00127 // Because SpectralModel is an abstract base class, an actual instance of this
00128 // class cannot be constructed. However the interface it defines can be used
00129 // inside a function. This is always recommended as it allows functions which
00130 // have SkyCompBase's as arguments to work for any derived class.
00131 // These examples are coded in the dSkyCompBase.cc file.
00132 // <h4>Example 1:</h4>
00133 // In this example the printComp function prints out the some basic information
00134 // on the spatial, spectral and flux properties of the component.
00135 // <srcblock>
00136 // void printComponent(const SkyCompBase & comp) {
00137 //  cout << "This component has a flux of " 
00138 //       << comp.flux().value() 
00139 //       << " " << comp.flux().unit().getName() << endl;
00140 //  cout << "and a " << ComponentType::name(comp.flux().pol()) 
00141 //       << " polarisation" << endl;
00142 //  cout << "This component has a " 
00143 //       << ComponentType::name(comp.shape().type()) << " shape" << endl;
00144 //  cout << "with a reference direction of " 
00145 //       << comp.shape().refDirection().getAngle("deg") << endl;
00146 //  cout << "This component has a " 
00147 //       << ComponentType::name(comp.spectrum().type()) << " spectrum" << endl;
00148 //  cout << "with a reference frequency of " 
00149 //       << comp.spectrum().refFrequency().get("GHz") << endl;
00150 // }
00151 // </srcblock>
00152 // </example>
00153 //
00154 // <motivation>
00155 // I wanted to force the interfaces of the SkyCompRep and the SkyComponent
00156 // classes to be the same. The best way I found was the introduction of a
00157 // base class that these other classes would derive from. 
00158 // </motivation>
00159 
00160 // <todo asof="1998/05/20">
00161 //   <li> Nothing I hope!
00162 // </todo>
00163 
00164 class SkyCompBase: public RecordTransformable
00165 {
00166 public:
00167 
00168   // The destructor does not anything
00169   virtual ~SkyCompBase();
00170 
00171   // return a reference to the flux of the component. Because this is a
00172   // reference, manipulation of the flux values is performed through the
00173   // functions in the Flux class. eg.,
00174   // <src>comp.flux().setValue(newVal)</src>. If the component flux varies with
00175   // frequency then the flux set using this function is the value at the
00176   // reference frequency.
00177   // <group>
00178   virtual const Flux<Double>& flux() const = 0;
00179   virtual Flux<Double>& flux() = 0;
00180   // </group>
00181 
00182   // return a reference to the shape of the component. Because this is a
00183   // reference, manipulation of the shape of the component is performed through
00184   // the functions in the ComponentShape (or derived) class. eg.,
00185   // <src>comp.shape().setRefDirection(newVal)</src>. To change the shape to a
00186   // different type you must use the <src>setShape</src> function.
00187   // <group>
00188   virtual const ComponentShape& shape() const = 0;
00189   virtual ComponentShape& shape() = 0;
00190   virtual void setShape(const ComponentShape& newShape) = 0;
00191   // </group>
00192   
00193   // return a reference to the spectrum of the component. Because this is a
00194   // reference, manipulation of the spectrum of the component is performed
00195   // through the functions in the SpectralModel (or derived) class. eg.,
00196   // <src>refFreq = comp.spectrum().refFrequency()</src>. Touse a different
00197   // spectral model you must use the <src>setSpectrum</src> function.
00198   // <group>
00199   virtual const SpectralModel& spectrum() const = 0;
00200   virtual SpectralModel& spectrum() = 0;
00201   virtual void setSpectrum(const SpectralModel& newSpectrum) = 0;
00202   // </group>
00203   
00204   // return a reference to the label associated with this component. The label
00205   // is a text string for general use.
00206   // <group>
00207   virtual String& label() = 0;
00208   virtual const String& label() const = 0;
00209   // </group>
00210 
00211   // return a reference to the label associated with this component. The label
00212   // is a text string for general use.
00213   // <group>
00214   virtual Vector<Double>& optionalParameters() = 0;
00215   virtual const Vector<Double>& optionalParameters() const = 0;
00216   // </group>
00217  
00218   // Return True if the component parameters are physically plausable. This
00219   // checks that I, Q, U, & V are all real numbers and if 
00220   // I^2 >= Q^2 + U^2 + U^2
00221   virtual Bool isPhysical() const = 0;
00222   
00223   // Calculate the flux at the specified direction & frequency, in a pixel of
00224   // specified x & y size.
00225   virtual Flux<Double> sample(const MDirection& direction, 
00226                               const MVAngle& pixelLatSize, 
00227                               const MVAngle& pixelLongSize, 
00228                               const MFrequency& centerFrequency) const = 0;
00229 
00230   // Same as the previous function except that many directions & frequencies
00231   // are done at once.  The flux is added into the values supplied in the
00232   // samples argument and this cube must have dimensions of [4, nDirs,
00233   // nFreqs]. The polarisations are always [I, Q, U, V] and units of the flux
00234   // added are specified with the reqUnits arguments.
00235   virtual void sample(Cube<Double>& samples,
00236                       const Unit& reqUnit,
00237                       const Vector<MVDirection>& directions, 
00238                       const MeasRef<MDirection>& dirRef, 
00239                       const MVAngle& pixelLatSize, 
00240                       const MVAngle& pixelLongSize, 
00241                       const Vector<MVFrequency>& frequencies,
00242                       const MeasRef<MFrequency>& freqRef) const = 0;
00243 
00244   // Return the Fourier transform of the component at the specified point in
00245   // the spatial frequency domain. The point is specified by a 3-element vector
00246   // (u,v,w) that has units of meters and the frequency of the observation, in
00247   // Hertz. These two quantities can be used to derive the required spatial
00248   // frequency <src>(s = uvw*freq/c)</src>. The w component is not used in
00249   // these functions.
00250 
00251   // The "origin" of the transform is the reference direction of the
00252   // component. This means, for symmetric components where the reference
00253   // direction is at the centre, that the Fourier transform will always be
00254   // real.
00255   virtual Flux<Double> visibility(const Vector<Double>& uvw,
00256                                   const Double& frequency) const = 0;
00257 
00258   // Same as the previous function except that many (u,v,w) points are done at
00259   // once. The visibilities are returned in the first argument which must have
00260   // dimensions of [4, nChan, nVis]. The points to sample are specified in the
00261   // second argument which must have dimensions of [3, nVis], and the
00262   // frequencies to sample are specified by the third argument which must have
00263   // a length of nChan. The units and polarisation of the returned visibilities
00264   // are the same as the flux of this object, and can be queried using the
00265   // <src>flux().units()</src> & <src>flux().pol()</src> functions.
00266   virtual void visibility(Cube<DComplex>& visibilities,
00267                           const Matrix<Double>& uvws,
00268                           const Vector<Double>& frequencies) const = 0;
00269 
00270   // This functions convert between a record and a component.  Derived classes
00271   // can interpret fields in the record in a class specific way. These
00272   // functions define how a component is represented in glish.  They return
00273   // False if the record is malformed and append an error message to the
00274   // supplied string giving the reason.
00275   // <group>
00276   virtual Bool fromRecord(String& errorMessage,
00277                           const RecordInterface& record) = 0;
00278   virtual Bool toRecord(String& errorMessage, 
00279                         RecordInterface& record) const = 0;
00280   // </group>
00281 
00282   // Function which checks the internal data of this class for correct
00283   // dimensionality and consistant values. Returns True if everything is fine
00284   // otherwise returns False.
00285   virtual Bool ok() const = 0;
00286 };
00287 
00288 } //# NAMESPACE CASA - END
00289 
00290 #endif