Module Measures

Description (classes)

Prerequisite

• Quanta module for units and quantities.

Etymology

Synopsis

Includes

	#include <measures/Measures.h>
	#include <measures/Measures/MDirection.h>

Measures

Measures are physical quantities within a certain reference frame. Examples are the Hour-angle and Declination of a source at a certain time and observatory; an Ra/Dec for a certain mean epoch; an apparent frequency at a certain time given in eV; a local sidereal time at an observatory.
Measures can be converted from one reference frame to another (and this possibility is its main reason for existence). A simple B1950-J2000 coordinate conversion example:

  cout <<       		// output
				// the conversion of a B1950 direction
	MDirection::Convert( MDirection( Quantity( 20, "deg"),
				         Quantity(-10, "deg"),
					 MDirection::Ref( MDirection::B1950)),
				// to J2000
			     MDirection::Ref( MDirection::J2000)) () 
				// where the constructor sets up a conversion
				// engine, and the operator() converts
		<< endl;

  // Set up the model for the input (default reference is UTC)
	MEpoch model (	Quantity(0., "d"));
  // Set up the frame with the observatory position
	MPosition obs(	MVPosition(	Quantity( 10, "m"),
					Quantity( -6, "deg"),
					Quantity( 50, "deg")),
			MPosition::Ref(MPosition::WGS84));
	Measframe frame( obs);
  // Set up the output reference
	MEpoch::Ref outref(	MEpoch::LAST,
				frame);
  // Set up conversion
	MEpoch::Convert	toLST(	model,
				outref);
  // Output a series of sidereal times (formatted in ddd::hh:mm:ss)
	for (Double d = 12345; d<12346; d += 0.1) {
	  cout << "Converted from UTC to LAST: " <<
		d <<  " : " <<
		toLST(d).getValue() << endl;
	};

The examples show the use of the 5 major classes involved in Measures:

   Base         Example               Description
  ------       ---------             -------------
  Measure      MEpoch          has a value and a  reference
  MeasValue    MVEpoch         value
  MeasRef      MEpoch::Ref     contains type, frame, offset
  MeasFrame    MeasFrame       contains Measures describing frame
  MeasConvert  MEpoch::Convert contains conversion information and engine

Each type of Measure has its own distinct class. Each is (weakly) derived from the Measure base class, and its name starts with an M. Examples are:

• MEpoch: an instance in time
• MDirection: a direction in space
• MPosition: a position on Earth
• MFrequency: the characteristics of a wave
• MDoppler: a Doppler shift
• MRadialVelocity: a radial velocity
• MBaseline: a baseline
• Muvw: a uvw value
• MEarthMagnetic: an earth' magnetic field value

The current set can be deduced from the class list at the end of the html version of this module description.

The main role of the Measure (and related) classes is to be able to convert an observed (or to be calculated) physical entity from one reference frame to another, e.g. a J2000 coordinate to galactic coordinates, or an TAI time to a local sidereal time (LAST). Simple unit conversions (e.g. an angle from mrad to deg), or calculations with values with attached units, are sufficiently catered for by the Quanta module classes.

Each measure has a value (MeasValue) and a reference (MeasRef).
The values are in general measure specific, weakly derived from MeasValue, and named with an initial MV. Examples are:

• MVEpoch (a high precision single value),
• MVDirection (direction cosines),
• MVPosition (3-vector positions),
• MVFrequency (single, unit depended value).
  
• MVDoppler (single, unit depended value)
• MVRadialVelocity (single value)

• MVAngle (to normalise and have specific I/O formatting for angle-like values)
• MVTime (same for time-like values)

	// An instance of time expressed in days (MJD) in UTC
	MEpoch date(MVEpoch(Quantity(50237.29, "d")),
		    MEpoch::Ref(MEpoch::UTC));
	// which could also be expressed as:
	MEpoch date(Quantity(50237.29, "d"),
		    MEpoch::UTC);
	// or using the default reference type:
	MEpoch date(Quantity(50237.29, "d"));
	// or as a time with an offset to a specific date:
	MEpoch date(Quantity(12.3, "h"),		// time
		    MEpoch::Ref(MEpoch::UTC,		// reference with
		    		MEpoch(Quantity(50237, "d"))));  // offset
	// A position of a telescope
	MPosition pos(MVPosition(Quantity(25, "m"),	// height
				 Quantity(20, "deg"),	// East longitude
				 Quantity(53, "deg")),	// lattitude
		      MPosition::WGS84);		// reference type
	// Use this position in a frame
	MeasFrame frame(pos);
	// Specify an LAST (in MGSD) observed at this position:
	MEpoch last(Quantity(51000.234, "d"),		// time and date
		    MEpoch::Ref(MEpoch::LAST,		// indicate LAST
				frame));		// and where observed
	// Maybe we know the MJD of the observed sidereal time,
	// but not its sidereal date. We could then specify it as an
	// offset to the beginning of the sidereal day in progress at
	// specified UTC
	MEpoch last(Quantity(13.45, "h"),		// time
		    MEpoch::Ref(MEpoch::LAST,		// indicate LAST
				frame,			// where observed
				MEpoch(51234,		// MJD of today
				       MEpoch::Ref(MEpoch::TAI + MEpoch::RAZE)));
	// where the RAZE indicates that the value will be truncated after
	// conversion. In this case it will be converted to LAST to be able
	// to add it as an offset to the specified LAST
	//
	// A direction (in RA/Dec) could be:
	MDirection coord(MVDirection(Quantity(54, "deg"),	// RA
				     Quantity(2034, "'")),	// DEC arcmin
			 MDirection::Ref(MDirection::J2000));	// J2000 type
	// If it were apparent coordinates, the time when observed should
	// have been known. We could just add it to the frame defined above,
	// and use it:
	frame.set(date);				// add time to frame
	MDirection acoord(MVDirection(Quantity(54, "deg"),	// RA
				      Quantity(2034, "'")),	// DEC
			  MDirection::Ref(MDirection::APP,	// apparent type
					  frame));		// and when
	// If it was given in HA/Dec, the position should have been known
	// as well, but it is already in the frame, hence we could say:
	MDirection acoord(MVDirection(Quantity(54, "deg"),	// HA
				      Quantity(2034, "'")),	// DEC
			  MDirection::Ref(MDirection::HADEC,	// type
					  frame));		// when/where

In the above examples in general explicit MV values have been used to specified the measure's value. In many cases (depending on the actual measure) it can be omitted, and the data can be given directly to the measure constructor. See the constructors for the individual measures for details.
If the reference is simple (i.e. no frame and/or offset) the Measure::Ref can be omitted, and only the code has to be specified.

	MeasFrame frame1(MEpoch(50236.12));
	MeasFrame frame2(frame1);

The value of a measure (in MV format) can be obtained with the getValue() member function. The value in a variety of formats and units can be obtained with a (specific Measure dependent) series of get() members of both the MV-value and the Measure.

Measures in themselves are not really necessary for proper data reduction and the like. Its real value is the ability to transform a Measure from one reference type (and frame, offset) to another.
Conversion of a measure of a certain kind from one reference to another is done with the aid of special, measure specific, MeasConvert classes. Each conversion class is called Measure::Convert (e.g. MDirection::Convert). A conversion generates from an input reference (or an input measure) and an output reference a conversion functional, that can be used to convert specific values.
Example:

  cout <<       		// output
				// the conversion of a B1950 direction
	MDirection::Convert( MDirection( Quantity( 20, "deg"),
				         Quantity(-10, "deg"),
					 MDirection::Ref( MDirection::B1950)),
				// to J2000
			     MDirection::Ref( MDirection::J2000)) () 
				// where the constructor sets up a conversion
				// engine, and the operator() converts
		<< endl;

  cout <<       		// output
				// the conversion of a B1950 direction
      MDirection::Convert(MDirection::Ref( MDirection::B1950),
				// to J2000
			    MDirection::Ref( MDirection::J2000))
				// and use conversion on value
				 (MVDirection( Quantity( 20, "deg"),
					       Quantity(-10, "deg")))
				// where the operator() converts
		<< endl;

	MDirection::Convert conv(MDirection::Ref( MDirection::B1950),
				 MDirection::Ref( MDirection::J2000));
	// We have some coordinates from somewhere, say coord(0:N-1):
	for (Int i=0; i<N; i++) {
	   cout << "B1950: " << coord(i) << "= J2000: " <<
		                conv(coord(i)) << endl;
      };

 // The observatory position. Note that the reference is geodetic position 
	MPosition myobs(MVPosition ( Quantity(1, "km") ,
				     Quantity(150, "deg"),
				     Quantity(20, "deg")),
				     MPosition::WGS84);
 // The time I want to observe (note that it could be specified in many
 // other ways)
	MEpoch obstime(MVEpoch(MVTime(1996, 5, 17, (8+18./60.)/24.)), 
	               MEpoch::UTC);
 // The frame specification for when and where to observe
	MeasFrame frame(myobs, obstime);
 // The reference for a sidereal time (note the frame could be empty and 
 // filled at the actual conversion time)
	MEpoch::Ref sidref( MEpoch::LAST, frame);
 // The reference for apparent coordinates:
	MDirection::Ref appref( MDirection::APP, frame);
 // The conversion engine for my time to LAST
	MEpoch::Convert tosid(obstime, sidref);
 // The conversion to sidereal time of obstime
	MEpoch sidtime = tosid();
 // Conversion of UTC 10.8 h 
	sidtime = tosid(MVEpoch(MVTime(1996, 5, 17, 10.8/24.))); 
 // Show me some time
	cout << "LAST for UTC = 11:00: " <<
		tosid(MVEpoch( MVTime( 1996, 5, 17, 11, 0))) << endl;
 // An offset reference (note the RAZE will keep only the integer part of
 // the day for the conversion result)
	MEpoch::Ref offtime(obstime.getValue(), MEpoch::UTC+MEpoch::RAZE);
 // The reference for a sidereal with respect to a specified offset (note
 // that it is automatically calculated into correct units)
	MEpoch::Ref sidoffref(MEpoch::LAST, frame, offtime);
 // Show the offset result
	cout << "LAST today: " <<
		MEpoch::Convert(11., sidoffref)() << endl;
 // Coordinate conversion from J2000
	cout << "Apparent coordinates: " <<
		MDirection::Convert ( MDirection(Quantum(11,"deg"),
                                               Quantum(-30, "deg")),
	                              MDirection::Ref( MDirection::APP,
	                                               frame))() << endl;
 // Handier to have the conversion engine available
	MDirection::Convert cvt( MDirection(Quantum(11,"deg"),
                                          Quantum(-30, "deg")),
	                         MDirection::Ref( MDirection::APP,
	                                          frame));
 // Set another frame time (note it is now sidereal, not UTC. The
 // frame will automatically convert it (using the frame again for
 // position) to TDB for precession etc calculations).
	frame.set(sidtime);
 // And look what same position is at this new time
	cout << "Next position: " << cvt() << endl;

Some conversions need maybe some fine tuning (e.g. what is the acceptable interval for Nutation linear interpolation: could be different from the default interval; some time calculations will want to use the predicted IERS values rather than the actual determined; some Nutation will maybe use the IERS updates, some maybe the JPL DE databases).
The AipsrcValue class can be used to specify very specific parameters that are used to steer the conversion process beyond what is possible with just a list of measure reference types (that list is already long for some cases). Values, switches can be set() (and removed) to change the default behaviour of the conversions. In general the user will only need to use the details in very specific cases. The details that can be used are described in the classes that provide calculations (e.g. Nutation), and in the aipsrc-data reference manual entry.

Some details about the different classes follows. In the examples often a specific measure value (e.g. MVEpoch, the MeasValue for MEpoch), or a specific measure (e.g. MDirection, a direction in space) is used. This is only to visualise the use, any other measure could have been used.

MeasValue

Measure

	M();			// some default, e.g. pole directoon, time ==0)
 	M(MV, MeasRef);
	M(Quantity, MeasRef);
	M(Quantum<Vector<Double> >, MeasRef);
	M(Vector<Quantity>, MeasRef);

Recall that a Measure is a value with a reference specified. The MeasConvert engines enable you to convert it into another Measure, with a different reference (e.g. from J2000 to AZEL). The different get() methods (either directly, or indirectly using additional MV get() functions, or Quantum conversion methods, can convert the internal value into a value (or values) with user preferred units.
For reasons of speed (and safety) the allowed reference types for each Measure are enumerated in each measure class. The different reference types for MDirection are, for example:

    		MDirection::J2000,
		MDirection::JMEAN,
		MDirection::JTRUE,
		MDirection::APP,
		MDirection::B1950,
		MDirection::BMEAN,
		MDirection::BTRUE,
		MDirection::GALACTIC,
		MDirection::HADEC,
		MDirection::AZEL,
		MDirection::DEFAULT = MDirection::J2000

Measure errors

MeasFrame

MeasRef

 	MEpoch mytime(MVEpoch(50236.5), MEpoch::UTC);
 // this will define a time in UTC on MJD 50236, 12 hours. The MVEpoch
 // explicit conversion could be left out for most compilers, but some
 // have trouble with automatic conversions.
 // Another way of doing it would be to use Quantities, which have
 // explicit constructors for all measures:
	MEpoch mytime(Quantity(50236.5, "d"));

 // Specify the location of the observatory (10m high, at given longitude
 // and latitude as geodetic position)
	MPosition obs( 	MVPosition( 	Quantity( 10, "m"),
					Quantity( -6, "deg"),
					Quantity( 52, "deg")),
			MPosition::WGS84);
 // If the current time is MJD50236, 12.3 h UTC, it could be specified as:
	MEpoch tim(	MVEpoch(	Quantity( 50236, "d"),
					Quantity( 12.3, "h")));
 // Note the default reference
 // For this example we will also specify it as:
	MEpoch offtim(tim); 
	offtim.set(MEpoch::DEFAULT+MEpoch::RAZE);
 // These two could define a frame
	MeasFrame frame(tim, obs);
 // Or maybe as (since observatory will stay put)
	MeasFrame frame1(obs);
 // and later addition of some time and its reference frame
	frame1.set(tim);
 // with a change to another time value at a later stage with
	frame1.resetEpoch(	MVEpoch(	Quantity( 50236, "d"),
					Quantity( 13, "h")));
 // At this time we observe a sidereal time of 2.3 h. The actual instance
 // of time needs a sidereal date to specify, but we are too lazy to
 // look it up, hence we specify that this time has an offset, equal to
 // the sidereal time at offtim (which with the RAZE addition will be
 // converted to an integral number of days in whatever time it is
 // converted to)
	MEpoch mylast(	MVEpoch(	Quantity( 2.3, "h")),
			MEpoch::Ref(	MEpoch::LAST,
					frame,
					offtim));
 // Which specifies that we have a Local apparent sidereal time of 2.3 h
 // at the position specified by obs in the frame, at an offset offtim.
 // Note that the offset is given in UTC (and RAZE). Any conversion of
 // this mylast value to any other reference type, will always auto start
 // with a conversion of the offset to the current type (i.e LAST (with
 // the RAZE taking the integer part only)), and adding it to the value
 // given. Note that if an output reference has an offset, the resulting
 // value will be corrected for the specified offset as well.

MeasConvert

 // The first argument will give the input reference, and, if a Quantum is
 // used to make the Measure, the default units for inputs to the conversion.
 // It acts as a 'model' for subsequent input to be converted.
 // () operator
	Measure::Convert(	Measure(Quantum), 
 // the second argument gives the output reference
				Measure::Ref);

	()		// convert the value as specified in the 'model'
	(Double)	// convert the value first to appropiate units (if they
			// were implicit in 'model' or explicitly set), and
			// then convert
	(Vector<Double>)// as Double
	(Quantity)	// convert the full value, including its own units
	(Quantum<Vector<Double> >) // as Quantity
	(MeasValue)	// convert the specified appropiate MV
	(Measure)	// set up a new conversion chain, using the value as
			// 'model', and the old output reference,
			//  and then convert
	(Measure, Measure::Ref) // set up a new conversion chain for the
			// 'model' given and the output reference given
	(Measure::Ref)	// set up a new conversion chain using the old 'model'
			// and the output reference given, and convert the
			// existing model value

  cout << 	
	MDirection::Convert( MDirection( Quantity( 20, "deg")
			   		 Quantity(-10, "deg"),
			     		 MDirection::Ref( MDirection::B1950)),
			     MDirection::Ref( MDirection::J2000)) () << endl;

 // Set up the model for the input (default reference is UTC)
	MEpoch model (	Quantity(0., "d"));
 // Set up the frame with the observatory position
	MPosition obs(	MVPosition(	Quantity( 10, "m"),
					Quantity( -6, "deg"),
					Quantity( 50, "deg")),
			MPosition::Ref(MPosition::WGS84));
	Measframe frame( obs);
 // set up the output reference
	MEpoch::Ref outref(	MEpoch::LAST,
				frame);
 // Set up conversion
	MEpoch::Convert	toLST(	model,
				outref);
 // Output a series of sidereal times (formatted in ddd::hh:mm:ss)
	for (Double d = 12345; d<12346; d += 0.1) {
	  cout << "Converted from UTC to LAST: " <<
		d <<
		toLST(d).getValue() << endl;
	};

For specific purposes it would be very easy to set up a series of simple classes, that would do standard conversions.

MeasData, MeasTable, MeasBase, other help classes

• MeasBase: base class (derived from Measure) for all real Measures
• MeasData: all constants, polynomial factors, interface to IERS database etc. which are not stored in Tables. (MeasTable looks after these). Mn short it provides all the actual data values necessary for the conversions (and the other help classes)
• MeasTable: interface for all data that comes from Tables rather than the program
• MeasIERS: (static) class to converse with the IERS database(s)
• MeasJPL: (static) class to converse with the JPL DE database(s)
• Precession: all precession related calculations
• Nutation
• Aberration
• SolarPos: all solarposition related calculations
• Euler: representation of Euler rotation angles
• RotMatrix: a 3-D rotation matrix

Motivation

To Do

• inlining

Example

Classes

Aberration -- Aberration class and calculations (full description)

EarthField -- EarthField class model calculations (full description)

EarthMagneticMachine -- Calculates magnetic field in a direction (full description)

IAU_SOFA -- Global Fortran function wraps (full description)

MBaseline -- A Measure: Baseline on Earth (full description)

MCBase -- Base for specific measure conversions (full description)

MCBaseline -- MBaseline conversion routines (full description)

MCDirection -- MDirection conversion routines (full description)

MCDoppler -- MDoppler conversion routines (full description)

MCEarthMagnetic -- MEarthMagnetic conversion routines (full description)

MCEpoch -- MEpoch conversion routines (full description)

MCFrame -- Measure frame calculations proxy (full description)

MCFrequency -- MFrequency conversion routines (full description)

MCPosition -- MPosition conversion routines (full description)

MCRadialVelocity -- MRadialVelocity conversion routines (full description)

MConvertBase -- Conversion of Measures Base (full description)

MCuvw -- Muvw conversion routines (full description)

MDirection -- A Measure: astronomical direction (full description)

MDoppler -- A Measure: Doppler shift (full description)

MEarthMagnetic -- A Measure: Magnetic field on Earth (full description)

MEpoch -- A Measure: instant in time (full description)

MFrequency -- A Measure: wave characteristics (full description)

MPosition -- A Measure: position on Earth (full description)

MRBase -- Base for Reference frame for physical measures (full description)

MRadialVelocity -- A Measure: radial velocity (full description)

MeasBase -- Base class for all measures (full description)

MeasComet -- Position for comets and other solar system bodies (full description)

MeasConvert -- Conversion of Measures (full description)

MeasData -- MeasData provides Measure computing data (full description)

MeasFrame -- Container for Measure frame (full description)

MeasFrameInterface -- Global functions (full description)

MeasIERS -- Interface to IERS tables (full description)

MeasJPL -- Interface to JPL DE tables (full description)

MeasMath -- Measure conversion aid routines (full description)

MeasRef -- Reference frame for physical measures (full description)

MeasTable -- MeasTable provides Measure computing database data (full description)

Measure -- Physical quantities within reference frame (full description)

MeasureHolder -- A holder for Measures to enable record conversions (full description)

MeasuresProxy -- (full description)

Muvw -- A Measure: uvw on Earth (full description)

Nutation -- Nutation class and calculations (full description)

Output -- Global functions (full description)

Output -- Global functions (full description)

Output -- Global functions (full description)

Output -- Global functions (full description)

ParAngleMachine -- Converts a direction into parallactic angle (full description)

Precession -- Precession class and calculations (full description)

SofaTest -- Wrapping of IAU SOFA Fortran routines and test class (full description)

SolarPos -- Solar position class and calculations (full description)

Stokes -- Stokes parameter definitions for interface to table data. (full description)

UVWMachine -- Converts UVW coordinates between coordinate systems (full description)

VelocityMachine -- Converts between velocities and frequencies (full description)