casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
Public Types | Public Member Functions | Static Public Member Functions | Private Member Functions | Friends
casa::Measure Class Reference

Physical quantities within reference frame. More...

#include <Measure.h>

Inheritance diagram for casa::Measure:
casa::MeasBase< Mv, Mr > casa::MeasBase< MVBaseline, MeasRef< MBaseline > > casa::MeasBase< MVDirection, MeasRef< MDirection > > casa::MeasBase< MVDoppler, MeasRef< MDoppler > > casa::MeasBase< MVEarthMagnetic, MeasRef< MEarthMagnetic > > casa::MeasBase< MVEpoch, MeasRef< MEpoch > > casa::MeasBase< MVFrequency, MeasRef< MFrequency > > casa::MeasBase< MVPosition, MeasRef< MPosition > > casa::MeasBase< MVRadialVelocity, MeasRef< MRadialVelocity > > casa::MeasBase< MVuvw, MeasRef< Muvw > >

List of all members.

Public Types

enum  Types {
  N_Types,
  DEFAULT
}
 Each derived class should have a Types enumeration, specifying the recognised frame types. More...
typedef void * Convert
 Each Measure should have typedefs of the form:

Public Member Functions

virtual ~Measure ()
 Destructor.
virtual void set (const MeasValue &dt)=0
 Each Measure should have the following set functions (with appropiate MVs and Ref):
virtual Bool putValue (const Vector< Quantum< Double > > &in)=0
virtual Bool setOffset (const Measure &in)=0
 Set the offset in the reference (False if non-matching Measure)
virtual Bool areYou (const String &tp) const =0
 Check the type of derived Measure entity (e.g.
virtual uInt type () const =0
 Get the type (== Register() of derived Measure (faster than Strings) All should have: static uInt myType();.
virtual void assured (const String &tp) const =0
 Assert that we are the correct Measure type.
virtual const StringtellMe () const =0
 Tell me your Measure type (e.g.
virtual String getRefString () const =0
 Each Measure should have the following static methods to give its name (e.g.
virtual Bool isModel () const
 Tell me if you are a pure model (e.g.
void dummy_giveMe () const
 Each derived class should have a string-to-code translation routine for the reference type.
virtual Bool setRefString (const String &in)=0
 Set the reference type to the specified String.
virtual const StringgetDefaultType () const =0
 Get the default reference type.
virtual const StringallTypes (Int &nall, Int &nextra, const uInt *&typ) const
 Get a list of all known reference codes.
virtual void checkTypes () const =0
 Check if all internal tables of types (both enum and String) are complete and correct.
void dummy_getRef () const
 Each class should have a function to return its reference:
void dummy_getValue () const
 Each derived class should be able to get its internal value and have:
virtual const UnitgetUnit () const =0
 Get unit (only available if Measure generated from a Quantum, else "")
virtual const MeasValuegetData () const =0
 Get data pointer (used by MeasConvert)
virtual MRBasegetRefPtr () const =0
 Get general reference pointer.
virtual void print (std::ostream &os) const =0
 Print a Measure.
virtual Measureclone () const =0
 Create a copy.

Static Public Member Functions

static uInt giveMe (const String &in, Int N_name, const String tname[])
 A general string checking routine to be used in derived measures.

Private Member Functions

void dummy_data () const
 Each class will have the following information: Actual data.
virtual void clear ()=0
 Clear the measure.

Friends

std::ostream & operator<< (std::ostream &os, const Measure &meas)
 Each derived class should have:

Detailed Description

Physical quantities within reference frame.

Intended use:

Public interface

Review Status

Reviewed By:
UNKNOWN
Date Reviewed:
before2004/08/25
Test programs:
tMeasure

Prerequisite

Etymology

Synopsis

Measure forms the abstract base class for physical quantities within a reference frame. Examples of derived classes are:

Measure is the generic name for the more specific instances like, e.g., MEpoch, an instant in time.
A Measure has both a value (specified in some value internal to the specific Measure, in general called MVMeasure (e.g. MVEpoch)), see MeasValue for general details; and a reference type and frame specifier (see MeasRef class).
The MeasRef specifies the reference type of the value, e.g. TAI, UTC, LAST. In addition the MeasRef specifies a possible offset (e.g. the beginning of the year, or today), and, if necessary, Measures necessary for defining the absolute quantity (e.g. an MPosition on Earth for LAST), using a reference frame specifier (see MeasFrame class).
The MeasRef class is templated, but typedefs exist (and should be used) to easily specify the correct one, e.g. MEpoch::Ref.
A Measure can be converted from one reference frame to another (e.g. an MDirection can be converted from J2000 to apparent coordinates) by setting up a measure specific conversion engine (see MeasConvert class and below). From an input MeasRef frame and an output MeasRef frame it constructs a conversion functional, that can be fed values (with the () operator).
Some conversions can, in addition to the main type (like TAI), specify details to completely describe any conversion process (e.g. the type of nutation calculation) by specifying Aipsrc keyword/value pairs.

Measures can in general be constructed from a MeasRef and a value. The value can be expressed in the internally used units (e.g. MVEpoch for MEpoch, MVDirection for MDirection), or as a Quantum, i.e. a value with a dimension (e.g. (20,"km/s")) (see Quantum class). The preferred way of construction is by using the constructor:

        Measure(MVmeasure, Measure::Ref)

where the reference can be omitted, defaulting to Measure::DEFAULT), or in simple cases (not needing additional frame information) be specified directly as a code (e.g. MEpoch::IAT).

The value of the Measure can be obtained by a variety of get functions, returning in general internal or Quantum values. The preferred way is a getValue(void), which returns the specific MVmeasure value, which can then be further formatted using the appropiate MVmeasure get() functions.
Special formatting (like hh:mm:ss.t, dd.mm.ss.t, yy/mm/dd etc) are catered for in conversion-type classes like MVAngle , MVTime .

Conversion (within a Measure type) from one reference frame to another is done by the MeasConvert class. The class is templated, but has typedefs Measure::Convert (e.g. MEpoch::Convert) for easy, and recommended, reference.
The basic constructors for a Measure::Convert are:

    // With a default Measure included
        Measure::Convert(Measure val, Measure::Ref outref);
    // With only input and output reference frames given 
        Mesaure::Convert( Measure::Ref inref, Measure::Ref outref);

The val is used as a model for subsequent input values into this conversion engine, including possible units; the outref specifies the output reference frame wanted. The constructor analyses the conversion wanted, and sets up a vector of routine calls to be called in sequence for the conversion. The actual conversion is done by the () operator.
To aid in using the raw measures, each class has also a Measure::MVType and Measure::MCType defined. They denote respectively the Measure Value class of the internal value, and the class with conversion routines.


Tip: In the member description a number of dummy routines are present; They are the only way I have found to get cxx2html to get the belonging text properly present;

Example

    #include <measures/Measures.h>
    #include <casa/Measure/MEpoch.h>
    // Example is only to show what can be done, not the easiest way
    // Set up a simple reference (no offset or secondary Measures). It
    // indicates that times are given in MJD TAI.
        MEpoch::Ref reftai(MEpoch::TAI);
    // Same, but indicating MJD UTC
         MEpoch::Ref refutc(MEpoch::UTC);
    // Set up an MEpoch (note that no reference is given. In that case a
    // default is assumed (for MEpoch UTC). MJD2000 is a provided constant
    // of the MJD at 2000.0
                MEpoch UTCval(Quantity(MeasData::MJD2000, "d"), reftai);
    // Set up, just for fun, an epoch, UTC for B1950.0:
        MEpoch val1950(Quantity(MeasData::MJDB1950, "d"));
    // and use it as an offset in a reference
        MEpoch::Ref ref1950(MEpoch::TAI, val1950);
    // An epoch for J2000 with an offset of B1950.0 will than be
        MEpoch val20_50(Quantity(MeasData::MJD2000-MeasData::MJDB1950, "d"),
                        ref1950);
    // Set up conversion from TAI(with values in days w.r.t. B1950.0) to UTC:
        MEpoch::Convert tai_to_utc(val20_50, refutc);
    // And convert a value (in this case the value in val20_50, the model)
    // from TAI(relative to B1950.0) to 'absolute' UTC
        MEpoch result = tai_to_utc();
    //   Show result
         cout << "Result 1: " << result << endl;
    // To convert 10 years since B1950.0
        result = tai_to_utc(Quantity(10.,"a"));
         cout << "Result 2: " << result << endl;
    // To convert any value in years(the last used units of the model) since B1950.0
        result = tai_to_utc(12.3);
         cout << "Result 3: " << result << endl;

Which generates the output:

        Result 1: Epoch: 51544::11:59:25.2154
        Result 2: Epoch: 36934::10:09:42.1283
        Result 3: Epoch: 37774::11:57:41.1085

Motivation

To be able to specify a physical entity absolutely in any reference frame; and to be able to convert from one frame to another. E.g. Local Sidereal Time to Temps Atomic International. A templated version for the MeasRef and MeasConvert was chosen to be able to check most arguments at compile time.

To Do

Definition at line 235 of file Measure.h.


Member Typedef Documentation

typedef void* casa::Measure::Convert

Each Measure should have typedefs of the form:

      typedef MeasConvert<class a_Measure, class its_MV, its_MC> Convert;
      typedef MeasRef<class a_Measure> Ref;

Dummy for cxx2html

Reimplemented in casa::MDirection, casa::MFrequency, casa::MEarthMagnetic, casa::MRadialVelocity, casa::MDoppler, casa::Muvw, casa::MEpoch, casa::MBaseline, and casa::MPosition.

Definition at line 263 of file Measure.h.


Member Enumeration Documentation

Each derived class should have a Types enumeration, specifying the recognised frame types.

It is formatted as:

        enum Types {
        CODE1,
        CODE2,
        ...,
        N_Types,                // Number of types
        SPEC1 = n,              // Possible special manipulator code
        .....,
        SYNONYM1 = CODEn,       // Probable synonyms
        ....,
        DEFAULT = CODEm};

Dummy for cxx2html

Enumerator:
N_Types 
DEFAULT 

Reimplemented in casa::MDirection, casa::MFrequency, casa::MRadialVelocity, casa::MDoppler, casa::MEarthMagnetic, casa::Muvw, casa::MEpoch, casa::MBaseline, and casa::MPosition.

Definition at line 254 of file Measure.h.


Constructor & Destructor Documentation

virtual casa::Measure::~Measure ( ) [virtual]

Destructor.


Member Function Documentation

virtual const String* casa::Measure::allTypes ( Int nall,
Int nextra,
const uInt *&  typ 
) const [virtual]

Get a list of all known reference codes.

nall returns the number in list, nextra the number of specials (like planets) that should be at end of list). typ returns the list of corresponding types. All should have

       static const String* allMyTypes(Int &nall, Int &nextra,
                                      const uInt *&typ);

Reimplemented in casa::MDirection, casa::MFrequency, casa::MEarthMagnetic, casa::MRadialVelocity, casa::Muvw, casa::MDoppler, casa::MEpoch, casa::MBaseline, and casa::MPosition.

virtual Bool casa::Measure::areYou ( const String tp) const [pure virtual]
virtual void casa::Measure::assured ( const String tp) const [pure virtual]
virtual void casa::Measure::checkTypes ( ) const [pure virtual]

Check if all internal tables of types (both enum and String) are complete and correct.

This function is called automatically if and when necessary.

Thrown Exceptions

  • AipsError if a (programming) error in the types.

All should have

       static void checkMyTypes();

Implemented in casa::MDirection, casa::MFrequency, casa::MEarthMagnetic, casa::MRadialVelocity, casa::Muvw, casa::MDoppler, casa::MEpoch, casa::MBaseline, and casa::MPosition.

virtual void casa::Measure::clear ( ) [private, pure virtual]
virtual Measure* casa::Measure::clone ( ) const [pure virtual]
void casa::Measure::dummy_data ( ) const [inline, private]

Each class will have the following information: Actual data.

        MVmeasure data;

Reference frame data

        MeasRef<Measure> ref;

Possible input units

        Unit unit;

And maybe later (or somewhere else)

        MeasErr error;

Dummy for cxx2html

Definition at line 446 of file Measure.h.

void casa::Measure::dummy_getRef ( ) const [inline]

Each class should have a function to return its reference:

        Measure::Ref getRef() const;

Dummy for cxx2html

Definition at line 388 of file Measure.h.

void casa::Measure::dummy_getValue ( ) const [inline]

Each derived class should be able to get its internal value and have:

        const MVmeasure &getValue() const;

To get dimensioned data, each derived class should contain the appropiate one of:

         Quantity get(const Unit &unit) const;
         Quantum<Vector<Double> > get(const Unit &unit) const;

Definition at line 402 of file Measure.h.

void casa::Measure::dummy_giveMe ( ) const [inline]

Each derived class should have a string-to-code translation routine for the reference type.

The routine returns False if unknown String (and a default mr), else an appropiate mr reference.

        Bool giveMe(Measure::Ref &mr, const String &in);
        static Bool getType(Measure::Types &tp, const String &in);

Dummy for cxx2html

Definition at line 340 of file Measure.h.

virtual const MeasValue* casa::Measure::getData ( ) const [pure virtual]
virtual const String& casa::Measure::getDefaultType ( ) const [pure virtual]
virtual MRBase* casa::Measure::getRefPtr ( ) const [pure virtual]
virtual String casa::Measure::getRefString ( ) const [pure virtual]

Each Measure should have the following static methods to give its name (e.g.

Epoch) or reference type (e.g. UTC):

      // Show the Measure type (e.g. "Direction")
         static const String &showMe();
      // Cast an integer to the appropriate reference type. Avaialable to provide
      // a safe cast in cases where Measure type is not explicitly known.
         static Measure::Types castType(uInt tp);
      // Show the reference type (e.g. MEpoch::showType(MEpoch::IAT) == "TAI")
         static const String &showType(uInt tp);
         static const String &showType(Measure::Types tp);

Implemented in casa::MDirection, casa::MFrequency, casa::MEarthMagnetic, casa::MRadialVelocity, casa::Muvw, casa::MDoppler, casa::MEpoch, casa::MBaseline, and casa::MPosition.

virtual const Unit& casa::Measure::getUnit ( ) const [pure virtual]
static uInt casa::Measure::giveMe ( const String in,
Int  N_name,
const String  tname[] 
) [static]

A general string checking routine to be used in derived measures.

Its arguments are the string to be converted (in), an array of strings to check against (tname), and its length (N_name). The check is case insensitive and mini-max. A return value less than N_name indicates success.

virtual Bool casa::Measure::isModel ( ) const [virtual]

Tell me if you are a pure model (e.g.

a planet)

Reimplemented in casa::MDirection, and casa::MEarthMagnetic.

virtual void casa::Measure::print ( std::ostream &  os) const [pure virtual]
virtual Bool casa::Measure::putValue ( const Vector< Quantum< Double > > &  in) [pure virtual]
virtual void casa::Measure::set ( const MeasValue dt) [pure virtual]
virtual Bool casa::Measure::setOffset ( const Measure in) [pure virtual]
virtual Bool casa::Measure::setRefString ( const String in) [pure virtual]

Set the reference type to the specified String.

False if illegal string, reference set to DEFAULT.

Implemented in casa::MDirection, casa::MFrequency, casa::MEarthMagnetic, casa::MRadialVelocity, casa::Muvw, casa::MDoppler, casa::MEpoch, casa::MBaseline, and casa::MPosition.

virtual const String& casa::Measure::tellMe ( ) const [pure virtual]
virtual uInt casa::Measure::type ( ) const [pure virtual]

Get the type (== Register() of derived Measure (faster than Strings) All should have: static uInt myType();.

Implemented in casa::MDirection, casa::MFrequency, casa::MEarthMagnetic, casa::MRadialVelocity, casa::Muvw, casa::MDoppler, casa::MEpoch, casa::MBaseline, and casa::MPosition.


Friends And Related Function Documentation

std::ostream& operator<< ( std::ostream &  os,
const Measure meas 
) [friend]

Each derived class should have:

        friend class MeasConvert<a_Measure, its_MV, its_MC>;

Output a Measure


The documentation for this class was generated from the following file: