measures - Module

Description

A measure is a quantity with a specified reference frame (e.g. UTC, J2000, mars). The measures module provides an interface to the handling of measures. The basic functionality provided is:

Conversion Conversion of measures, especially between different frames (e.g. UTC to LAST)
Calculation Calculation of e.g. a rest frequency from a velocity and a frequency.

This functionality is provided in both a command line interface and a GUI interface.

To access the measures module, include the measures.g Glish script. This will create a default Measures tool called dm.

Altough a Measures tool has state (it remembers the frame you are working in), there is only in very special cases the need to create your own tool . Just use the default dm one. However, if you do require one, perhaps to distinguish working in two different environment frames for an input observation and and output display, then use the measures constructor to make one:

- include 'measures.g';
- mydm := measures();		# measures tool created for you
- mydm.type();  
measures

In normal use, the measures tool will be operated using a GUI. All operations can be done from either the command line or the GUI. The aipsrc mechanism is used by the measures tool to specify certain operational details (like using DE405 rather than the default DE200 for planetary positions).

Measures

Measures are e.g. an epoch, or coordinates, which have, in addition to values (as quantities), also a reference specification, and possibly an offset. They are represented as records with fields describing the various entities embodied in the measure. These entities can be obtained by the access methods gettype, getref, getoffset. getvalue.

Each measure has its own list of reference codes (see the individual methods for creating them, like direction). If an empty or no code reference code is given, the default code for that type of measure will be used (e.g. it is J2000 for a direction). If an unknown code is given, this default is also returned, but with a warning message.

The values of a measure (like the right-ascension for a direction) are given as quantities. Each of them can be either a scalar quantity with a scalar or vector for its actual value (see the following example). The values can also be given as an r_array, in which case each element of that array will be used as a value. E.g a vector of length 2 of quanta will be seen in a direction constructor as a longitude and a latitude.

- dm.epoch('utc','today')	# note that your value will be different
[type=epoch, refer=UTC, m0=[value=51350.0778, unit=d]] 
- dm.direction('j2000','5h20m','-30.2deg')
[type=direction, refer=J2000, m1=[value=-0.527089434, unit=rad],
		  m0=[unit=rad, value=1.3962634]] 
- a := dm.direction('j2000','5h20m','-30.2deg')
- dm.gettype(a)
direction 
- dm.getoffset(a)
F 
- dm.getref(a)
J2000 
- dm.getvalue(a)  
[*53=[unit=rad, value=1.3962634], *54=[value=-0.527089434, unit=rad]] 
- dm.getvalue(a)[1]
[unit=rad, value=1.3962634] 
- dm.getvalue(a)[2]
[value=-0.527089434, unit=rad] 
- # try as a scalar quantity with multiple values
- a := dm.direction('j2000', dq.quantity([10,20],'deg'),           
+ dq.quantity([30,40], 'deg'))
- dm.getvalue(a)[1]
[unit=rad, value=[0.174532925 0.34906585] ] 
- dq.getvalue(dm.getvalue(a)[1])[2]
0.34906585 
- a
[type=direction, refer=J2000, m1=[value=[0.523598776 0.698131701] , unit=rad],
	 m0=[unit=rad, value=[0.174532925 0.34906585] ]] 
- # try as an r_array
- b := r_array(,2)
- r_fill(dq.quantity([10,20],'deg'), b, 1)
T 
- r_fill(dq.quantity([30,40],'deg'), b, 2)
T 
- a := dm.direction('j2000', b)
- dm.getvalue(a)
[*61=[unit=rad, value=[0.174532925 0.34906585] ],
		 *62=[value=[0.523598776 0.698131701] , unit=rad]]

Known measures are:

epoch: an instance in time (internally expressed as MJD or MGSD)
direction: a direction towards an astronomical object (including planets, sun, moon)
position: a position on Earth
frequency: electromagnetic wave energy
radialvelocity: radial velocity of astronomical object
doppler: doppler shift (i.e. radial velocity in non-velocity units like 'Optical', 'Radio'. The radialvelocity GUI caters for Doppler coding as well)
baseline: interferometer baseline
uvw: UVW coordinates
earthmagnetic: Earth' magnetic field

In addition to the reference code (like J2000), a measure needs sometimes more information to be convertable to another reference code (e.g. a time and position to convert it to an azimuth/elevation). This additional information is called the reference frame, and can specify one or more of 'where am i', 'when is it', 'what direction", 'how fast'.

The frame values can be set by the doframe tool function, or by a menu on the measure guis.

Since you would normally work from a fixed position, the position frame element ('where you are'), can be specified in your .aipsrc if its name is in the Observatory list (obslist) tool function. You can set your preferred position by adding to your .aipsrc file:

measures.default.observatory:	atca

More information on the individual measures can be found in the GUI descriptions for epoch; direction; position; frequency; radialvelocity; doppler.

Example
Suppose we have an object with a J2000 right ascension and declination, and want to know the time of rising above the horizon of a certain astronomical direction. In practice you would do this using the special application in the gui, but the following shows how to do it the hard and long way.

- include 'measures.g'						# 1
T
- tim := dm.epoch('utc','today')				# 2
- tim
[type=epoch, refer=UTC, m0=[value=51350.0934, unit=d]] 
- pos := dm.observatory('ATCA')					# 3
- dm.doframe(tim) 						# 4 
T 
- dm.doframe(pos)               				# 5
T 
- coord := dm.direction('J2000', '5h20m30.2', '-30d15m12.5') 	# 6
- hadec := dm.measure(coord,'hadec')				# 7
- last := dm.measure(tim,'last')				# 8
- sdec := dq.sin(dm.getvalue(hadec)[2])				# 9
- cdec := dq.cos(dm.getvalue(hadec)[2])
- clat := dq.cos(dm.getvalue(pos)[2])
- slat := dq.sin(dm.getvalue(pos)[2])
- ha := dq.acos(dq.neg(dq.div(dq.mul(sdec, slat),
					 dq.mul(cdec, clat))))  #10
- dq.norm(dq.add(ha, dm.getvalue(coord)[1]), 0)			#11
[value=189.926855, unit=deg] 
- dq.time(dq.norm(dq.add(ha, dm.getvalue(coord)[1]), 0))	#12
12:39:42.445 
- rt := dq.totime(dq.norm(dq.add(ha, dm.getvalue(coord)[1])))	#13
- rt
[value=-0.472425402, unit=d] 
- rtoff := dm.epoch('r_utc', dm.getvalue(tim)[1])		#14
- rtoff
[type=epoch, refer=R_UTC, m0=[value=51350, unit=d]] 
- rte := dm.epoch('last', rt, off=rtoff)			#15
- rte
[type=epoch, refer=LAST, m0=[value=58062.5276, unit=d]] 
- dm.measure(rte, 'utc')					#16
[type=epoch, refer=UTC, m0=[value=51349.3674, unit=d]] 
- dq.time(dm.getvalue(dm.measure(rte, 'utc'))[1], form="ymd time")
1999/06/20/08:48:59.738 
- dq.time(dm.getvalue(dm.measure(dm.measure(rte, 'utc'), 'last'))[1]) #17
12:39:42.445 
- # try it another way
- tim := dm.epoch('utc', 'today')				#18
- tim := dm.measure(tim,'tai')					#19
- dm.doframe(tim)						#20
T
- dm.showframe(F)						#21
position: 09:58:12.033 -030.08.43.736 6372960.26 m ITRF
epoch: 2002/10/18/00:15:49 UTC
T 
- is_measure(tim)						#22
T 
- sun:=dm.direction('sun')					#23
- dm.rise(sun)							#24
[rise=[value=20.4413559, unit=deg], set=[value=158.042775, unit=deg]] 
- dm.rise(sun,'10deg') 						#25
[rise=[value=27.3170864, unit=deg], set=[value=151.167045, unit=deg]] 
- dq.form.long(dm.rise(sun).rise)				#26
01:21:45.925 
- dq.setformat('long','dms')					#27
T 
- dq.form.long(dm.rise(sun).rise)
+020.26.28.881

1.

Gives access to the measures, with a default server dm

2.

Get the time now as an epoch measure

3.

Get the position of an observatory

4.

Set the time in reference frame. Note that if you are working in a GUI environment, the frame set will be displayed. If working in a pure CLI environment, the current frame can be shown with the showframe tool function.

5.

Set the position in reference frame

6.

Get the coordinates as a measure

7.

Convert the coordinates to hour-angle, declination

8.

Get the sidereal time for now (just for the fun)

9.

Calculate the sines/cosines of declination and latitudes

10.

Get the hour-angle for zero elevation

11.

Get the sidereal time of setting (rising?), normalised between 0 and 360 degrees

12.

Show it in a time format

13.

Save it as a time (remember, we calculated it as an angle)

14.

We would like to convert this sidereal time (rte) back to UTC. To be able to do that, we most now when (for which date) the sidereal time is valid. In general we do not know the Sidereal date, else it would be easy. We can however, specify an offset with a measure. Special reference codes are available (called 'raze'), which will after conversion only retain the integral part. This line says that we specify tim as an epoch in UTC, to be razed after conversion. If we now use this as an offset for a sidereal time, the offset will be automatically converted to sidereal time (since it has to be added to a sidereal time), razed, i.e. giving the Greenwich sidereal date, and hence the complete epoch is known. (Note that the indecision over the 4 minutes per day has to be handled in special cases).

15.

We can now define our sidereal time rt as a real epoch

16.

We now convert the sidereal time rte, to an UTC, and show it as a time as well

17.

We do not trust this funny razing, and convert the UTC obtained straight back to a sidereal time. And, indeed it worked (compare line 12)

18.

Another time

19.

Convert it to TAI (just to show how to do it)

20.

Frame it

21.

Show the current frame (the F argument indicates to not use GUI if one present) (note that the position is set to ATCA, as defined by the .aipsrc variable). If an error happens, the command

dm.doframe(dm.observatory('atca'))

will solve it.

22.

to check if we really got a measure, or an error occurred.

23.

define the position of the sun (the actual position will be at the frame time)

24.

get the sidereal time of rise/set of the sun (at the default elevation of 5 deg)

25.

try again for an elevation of 10 deg

26.

display the rise sidereal time as a 'longitude'. A variety of dq.form.x routines exist, using a global format setting mechanism (in general you have your preferred way to display something)

27.

change the format, and show again

The above could be done using the GUI (start it with dm.gui()), setting your position in the Frame menu option, and using the rise/set application. Another option would be to use the direction GUI (from the Tool menu in the general GUI or starting dm.directiongui() from the command line); selecting the Sun as planet; setting the position in the frame menu and the time; Convert to J2000, and select rise/set from the Info menu.

If at one stage you want to use a GUI result on the command line, the 'copy' button will transfer the last result to the clipboard (and read it with the normal clipboard operation

- dcb.paste()
[type=direction, refer=J2000, m1=[value=0.669116295, unit=rad], m0=[unit=rad, value=0.0259745717]]

Tools

measures	measures tool
measuresgui	gui code for measures.g

Functions

is_measure Check if measure

Next: is_measure - Function Up: General Previous: msplotapplyflags - Function Contents Index