MFrequency.h

Go to the documentation of this file.
00001 //# MFrequency.h: A Measure: wave characteristics
00002 //# Copyright (C) 1995,1996,1997,1998,1999,2000,2001,2002,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$
00028 
00029 #ifndef MEASURES_MFREQUENCY_H
00030 #define MEASURES_MFREQUENCY_H
00031 
00032 //# Includes
00033 #include <casacore/casa/aips.h>
00034 #include <casacore/measures/Measures/MeasBase.h>
00035 #include <casacore/measures/Measures/MeasRef.h>
00036 #include <casacore/casa/Quanta/MVFrequency.h>
00037 
00038 namespace casacore { //# NAMESPACE CASACORE - BEGIN
00039 
00040 //# Forward Declarations
00041 class MFrequency;
00042 class MCFrequency;
00043 class MDoppler;
00044 class MVDoppler;
00045 template <class M> class MeasConvert;
00046 template <class M> class ArrayMeasColumn;
00047 template <class M> class ScalarMeasColumn;
00048 
00049 //# Typedefs
00050 
00051 // <summary>
00052 // A Measure: wave characteristics
00053 // </summary>
00054 
00055 // <use visibility=export>
00056 
00057 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tMeasure" demos="">
00058 // </reviewed>
00059 
00060 // <prerequisite>
00061 //   <li> <linkto class=Measure>Measure</linkto> class 
00062 //   <li> <linkto class = MRadialVelocity>MRadialVelocity</linkto> class
00063 //              for some other background.
00064 // </prerequisite>
00065 //
00066 // <etymology>
00067 // </etymology>
00068 //
00069 // <synopsis>
00070 // MFrequency is a derived Measure class for wave characteristics.<br>
00071 // An MFrequency can be generated from a simple value (or an
00072 // <linkto class=MVFrequency>MFrequency</linkto> object), which is then
00073 // interpreted as a frequency in Hz, and a reference, with an LSRK type
00074 // as default.<br>
00075 // It can also be generated from a Quantity, where the interpretation
00076 // depends on the dimensionality of the Quantity:
00077 // <ul>
00078 // <li> time (e.g. s): period
00079 // <li> frequency (e.g. Hz): frequency
00080 // <li> angular frequency (e.g. arcmin/s): angular frequency
00081 // <li> length (e.g. cm): wavelength
00082 // <li> inverse length (e.g. mm<sup>-1</sup>): wave number
00083 // <li> energy (e.g. J.s): energy (i.e. <em>h.nu</em>)
00084 // <li> momentum (e.g. kg.m): <em>m.c/h</em>
00085 // </ul>
00086 // The different reference types of a frequency are:
00087 // <ul>
00088 //  <li> MFrequency::REST -- Rest frequency
00089 //  <li> MFrequency::LSRD -- Local Standard of Rest (J2000) -- as the
00090 //              dynamical definition (IAU, [9,12,7] km/s in galactic
00091 //              coordinates)
00092 //  <li> MFrequency::LSRK -- LSR as a kinematical (radio) definition --
00093 //              20.0 km/s in direction ra,dec = [270,+30] deg (B1900.0)
00094 //  <li> MFrequency::BARY -- Barycentric (J2000)
00095 //  <li> MFrequency::GEO --- Geocentric
00096 //  <li> MFrequency::TOPO -- Topocentric
00097 //  <li> MFrequency::GALACTO -- Galacto centric (with rotation of 220 km/s
00098 //              in direction l,b = [90,0] deg.
00099 //  <li> MFrequency::LGROUP -- Local group velocity -- 308km/s towards
00100 //               l,b = [105,-7] deg (F. Ghigo)
00101 //  <li> MFrequency::CMB -- CMB velocity -- 369.5km/s towards
00102 //              l,b = [264.4, 48.4] deg (F. Ghigo)
00103 //  <li> MFrequency::DEFAULT = LSRK
00104 // </ul>
00105 // <p>
00106 // Conversion between the different types is done with the standard
00107 // <linkto class=MeasConvert>MeasConvert</linkto> class 
00108 // (<src>MFrequency::Convert</src> in this case). 
00109 // Some of the conversions are only possible if frame information has been 
00110 // filled in. The following frame information is necessary if a conversion
00111 // goes to or from the (different) specified types:
00112 // <ul>
00113 //  <li><em>Radial Velocity</em>: REST
00114 //  <li><em>Epoch</em>: TOPO, GEO
00115 //  <li><em>Position</em>: TOPO
00116 //  <li><em>Direction</em> all
00117 // </ul>
00118 // <br>
00119 // To accommodate unknown or invalid frames, the additional reference type
00120 // <ul>
00121 //  <li> MFrequency::Undefined
00122 // </ul>
00123 // is available. Conversions to/from Undefined are not possible. 
00124 // If attempted, an exception will be thrown.
00125 // The name was chosen to be Undefined and not UNDEFINED in order to
00126 // not collide with the (ugly) WCSLIB macro of the upper case name
00127 // and in concordance with Stokes::Undefined.
00128 // <br>
00129 // An MFrequency can be created from an
00130 // <linkto class=MDoppler>MDoppler</linkto> (and a rest frequency, (the
00131 // <linkto class=QC>QC</linkto> class contains at least <src>QC::HI</src>))
00132 // by the <src>fromDoppler()</src> member. It can be converted to an MDoppler
00133 // with the <src>toDoppler()</src>. Comparable methods will be available
00134 // for <linkto class=MFrequency>MFrequency</linkto> as 
00135 // <src>toRadial()</src> and <src>fromRadial</src>.<br>
00136 // If the Doppler shift is known (e.g. from another spectral line), the
00137 // REST frequency can be determined with the <src>toREST()</src> member.
00138 // <note role=caution> Conversion between the different frequencies can,
00139 // due to relativistic effects, only be done approximately for very high
00140 // (order c) radial velocities (shifted frequencies). A better approach
00141 // would be to start from radial velocities and a rest frequency.
00142 // </note>
00143 // </synopsis>
00144 //
00145 // <example>
00146 // Get the Doppler shift for an oberved HI frequency of 1380 MHz
00147 // <srcblock>
00148 //      cout << "Redshift for 1380 MHz: " <<
00149 //              MDoppler::Convert( MFrequency( Quantity(1380., "MHz"),
00150 //                                             MFrequency::TOPO).toDoppler(QC::HI),
00151 //                                 MDoppler::Z)() << endl;
00152 // </srcblock>                             
00153 // </example>
00154 //
00155 // <motivation>
00156 // </motivation>
00157 //
00158 // <todo asof="2003/03/03">
00159 // </todo>
00160 
00161 class MFrequency : public MeasBase<MVFrequency, MeasRef<MFrequency> > {
00162 
00163  public:
00164   //# Friends
00165   // Conversion of data
00166   friend class MeasConvert<MFrequency>;
00167 
00168   //# Enumerations
00169   // Types of known MFrequencies
00170   // <note role=warning> The order defines the order in the translation
00171   // matrix FromTo
00172   // in the getConvert routine. Do not change the order without
00173   // changing the array. Additions should be made before N_types, and
00174   // an additional row and column should be coded in FromTo, and
00175   // in showType().</note>
00176   enum Types {
00177     REST,
00178     LSRK,
00179     LSRD, 
00180     BARY,
00181     GEO,
00182     TOPO,
00183     GALACTO,
00184     LGROUP,
00185     CMB,
00186     N_Types,
00187     Undefined = 64,
00188     N_Other,
00189     // all extra bits
00190     EXTRA = 64,
00191     // Defaults
00192     DEFAULT=LSRK,
00193     // Synonyms
00194     LSR=LSRK };
00195 
00196   //# Typedefs
00197   // Measure value container for this class (i.e. MFrequency::MVType)
00198   typedef MVFrequency MVType;
00199   // Measure conversion routines for this class (i.e. MFrequency::MCType)
00200   typedef MCFrequency MCType;
00201   // Measure reference (i.e. MFrequency::Ref)
00202   typedef MeasRef<MFrequency> Ref;
00203   // Measure conversion use (i.e. MFrequency::Convert)
00204   typedef MeasConvert<MFrequency> Convert;
00205   // Measure table Columns (e.g., MFrequency::ScalarColumn)
00206   typedef ScalarMeasColumn<MFrequency> ScalarColumn;
00207   typedef ArrayMeasColumn<MFrequency> ArrayColumn;
00208   // Reference enum Types (included originally for gcc 2.95)  
00209   typedef WHATEVER_SUN_TYPEDEF(MFrequency) Types Types;
00210 
00211   //# Constructors
00212   // <note role=tip> In the following constructors and other functions, all 
00213   // <em>MeasRef</em> can be replaced with simple <src>Measure::TYPE</src>
00214   // where no offsets or frames are needed in the reference. </note>
00215   // Default constructor; generates a zero rest frequency
00216   MFrequency();
00217   // Create from data and reference
00218   // <group>
00219   MFrequency(const MVFrequency &dt);
00220   MFrequency(const MVFrequency &dt, const MFrequency::Ref &rf);
00221   MFrequency(const MVFrequency &dt, MFrequency::Types rf);
00222   MFrequency(const Quantity &dt);
00223   MFrequency(const Quantity &dt, const MFrequency::Ref &rf);
00224   MFrequency(const Quantity &dt, MFrequency::Types rf);
00225   MFrequency(const Measure *dt);
00226   MFrequency(const MeasValue *dt);
00227   // </group>
00228   
00229   //# Destructor
00230   virtual ~MFrequency();
00231   
00232   //# Operators
00233   
00234   //# General Member Functions
00235   // Tell me your type
00236   // <group>
00237   virtual const String &tellMe() const;
00238   static const String &showMe();
00239   virtual uInt type() const;
00240   static void assure(const Measure &in);
00241   // </group>
00242   // Translate reference code. The uInt version has a check for valid codes
00243   // (i.e. it is a safe cast).
00244   // <thrown>
00245   //   <li> AipsError in the uInt interface if illegal code given
00246   // </thrown>
00247   // <group>
00248   static MFrequency::Types castType(uInt tp);
00249   static const String &showType(MFrequency::Types tp);
00250   static const String &showType(uInt tp);
00251   // </group>
00252   // Translate string to reference code
00253   // <group>
00254   static Bool getType(MFrequency::Types &tp, const String &in);
00255 
00256   // Throws an exception if the type string is not recognized
00257   static MFrequency::Types typeFromString(const String& in);
00258 
00259 
00260   Bool giveMe(MFrequency::Ref &mr, const String &in);
00261   // </group>
00262   // Set the offset in the reference (False if non-matching Measure)
00263   virtual Bool setOffset(const Measure &in);
00264   // Set the reference type to the specified String. False if illegal
00265   // string, reference set to DEFAULT.
00266   virtual Bool setRefString(const String &in);
00267   // Get the default reference type
00268   virtual const String &getDefaultType() const;
00269   // Get a list of all known reference codes. nall returns the number in list,
00270   // nextra the number of specials (like planets) that should be at 
00271   // end of list). typ returns the list of corresponding types.
00272   // <group>
00273   virtual const String* allTypes(Int &nall, Int &nextra,
00274                                  const uInt *&typ) const;
00275   static const String* allMyTypes(Int &nall, Int &nextra,
00276                                   const uInt *&typ);
00277   // </group>
00278   // Check if all internal tables of types (both enum and String) are 
00279   // complete and correct. This function is called automatically if and when
00280   // necessary.
00281   // <thrown>
00282   //   <li> AipsError if a (programming) error in the types.
00283   // </thrown>
00284   // <group> 
00285   virtual void checkTypes() const;
00286   static void checkMyTypes();
00287   // </group>
00288   // Get the reference type (for records, including codes like R_)
00289   virtual String getRefString() const;
00290   // Get my type (as Register)
00291   static uInt myType();
00292   
00293   // Get frequency in specified units
00294   Quantity get(const Unit &un) const;
00295   
00296   // Make a Doppler velocity from the frequency and the specified rest frequency
00297   // <group>
00298   MDoppler toDoppler(const MVFrequency &rest);
00299   MDoppler toDoppler(const MVFrequency &rest) const;
00300   // </group>
00301   // Local use only
00302   static MDoppler toDoppler(const Measure &in, const MVFrequency &rest);
00303   // Make a frequency from the Doppler velocity and the specified rest frequency
00304   // (default reference type LSRK)
00305   // <group>
00306   static MFrequency fromDoppler(const MDoppler &dop,
00307                                 const MVFrequency &rest);
00308   static MFrequency fromDoppler(const MDoppler &dop,
00309                                 const MVFrequency &rest,
00310                                 MFrequency::Types type);
00311   // For internal use only
00312   static MFrequency fromDoppler(const Measure &dop,
00313                                 const MVFrequency &rest,
00314                                 MFrequency::Types type);
00315   // </group>
00316   
00317   // Make a rest frequency using a Doppler velocity
00318   MFrequency toRest(const MDoppler &dop);
00319   // For local use only
00320   static MFrequency toRest(const Measure &in, const Measure &dop);
00321   
00322   // Make a copy
00323   // <group>
00324   virtual Measure *clone() const;
00325   // </group>
00326   
00327  private:
00328   //# Enumerations
00329   
00330   //# Data
00331   
00332   //# Member functions
00333   
00334 };
00335 
00336 
00337 } //# NAMESPACE CASACORE - END
00338 
00339 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1