Subject: Brief Summary of OGIP/93-001 (Physical units in FITS files)

From: [email-masked] (Ian M George, Code 668, NASA/GSFC, USA (Usque ad mortem bibendum))
Date: Thu, 15 Apr 93 11:51:55 -0400

Since Lorella & I inadvertantly opened a world-wide Pandora's box with our
message to the heafits exploder yesterday, below we breifly list the proposed 
strings to specify physical units within FITS files. A couple of the 
(more constructive, physically plausible) suggestions recieved so far
are tacked on the end.

The memo itself is available via anonymous ftp on legacy.gsfc.nasa.gov
(128.183.8.233) in the .caldb/docs/memos directory:
	ogip_93_001.tex		is the LaTeX source
	ogip_93_001.ps  	is a PS version of the complete doc.
(Note, I'm having some difficulty with PS "standards" (ha !) at present, 
thus unfortunately I can't guarentee it will print on all printers)

Constructive comments are welcomed (I suggest to heafits)...
					.... Let the Games begin

Ian M George 
HEASARC				([email-masked])

BRIEF OVERVIEW 
--------------
In the memo we give 3 tables of proposed strings:
 Table 1 for IAU-recommended units
 Table 2 for addition allowed units convenient for astronomy
 Table 3 for further allowed (but discouraged) convenient units
It should be noted that wherever possible made the string the same as the 
corresponding IAU-recommended symbol. Notable exceptions are when the 
symbol is not part of the standard ASCII character set or when it would 
lead to potential upper/lower case confusion with another string.

The final section of the memo then discusses proposed rules for the 
construction of compound units.

TABLE 1 - Highly recommended
---------------------------------------------------------------------------
Quantity		& Proposed 	& Meaning		 
			& String
---------------------------------------------------------------------------
	(SI base & supplementary units)
length			& 'm'		& metre
mass			& 'kg'		& kilogram	
time			& 's'		& second of time (incl sidereal time)
plane angle		& 'rad'		& radian	
solid angle		& 'sr'		& steradian	
temperature		& 'K'		& kelvin	
electric current	& 'A'		& ampere
amount of substance	& 'mol'		& mole	
luminous intensity	& 'cd'		& candela	
	(IAU-recognized derived units)
frequency		& 'Hz'		& hertz		
energy			& 'J'		& joule		
power			& 'W'		& watt		
electric potential	& 'V'		& volts		
force			& 'N'		& newton	
pressure, stress	& 'Pa'		& pascal
electric charge		& 'C'		& coulomb	
electric resistence	& 'ohm'		& ohm	
electric conductance	& 'siemen'	& siemens	
electric capacitance	& 'F'		& farad		
magnetic flux		& 'Wb'		& weber		
magnetic flux density	& 'T'		& tesla	
inductance		& 'H'		& henry		
luminous flux		& 'lm'		& lumen	
illuminance		& 'lx'		& lux	
---------------------------------------------------------------------------

TABLE 2 - Also Recommended
---------------------------------------------------------------------------
Quantity		& Proposed 	& Meaning		 
			& String
---------------------------------------------------------------------------
plane angle		& 'deg'		& degree of arc	
energy			& 'keV'		& kiloelectron volt
			& 'erg'		& erg
length			& 'angstrom'	& angstrom 
events			& 'count' 	& (detected) counts 
flux 			& 'mag'		& (stellar) magnitude
area			& 'pixel'	& (image/detector) pixel 
---------------------------------------------------------------------------

TABLE 3 Allowed, but discouraged
---------------------------------------------------------------------------
Quantity		& Proposed 	& Meaning		 
			& String
---------------------------------------------------------------------------
time			& 'us'		& microsecond   (note the "u")
			& 'ms'		& millisecond 	
			& 'min'		& minute (incl sidereal time)
			& 'h'		& hour (incl sidereal time)
			& 'd'		& day 
			& 'yr'		& year (Julian)
plane angle		& 'arcsec'	& second of arc 
			& 'arcmin'	& minute of arc	
length			& 'um'		& micrometre (or micron - note the "u")
			& 'mm'		& millimetre 
			& 'cm'		& centimetre	
			& 'km'		& kilometre	
			& 'AU'		& astronomical unit 
			& 'lyr'		& light year
			& 'pc'		& parsec
area			& 'barn'	& barn
energy			& 'eV'		& electron volt
			& 'Mev'		& megaelectron volts 
			& 'GHz'		& gigahertz	
mass			& 'g'		& gram 	
events			& 'photon' 	& (detected) photons 
temperature		& 'C'		& degrees celsius 
flux density		& 'Jy'		& jansky
			& 'mCrab'	& millicrab (yuk, yuk, yuk)
magnetic field		& 'gauss'	& gauss (note not using 'G')
---------------------------------------------------------------------------

RULES FOR CONSTRUCTION OF COMPOUND UNITS
----------------------------------------

The rules for the construction of compound units are fairly straightforward, 
involving standard characters preceeding or following the string specifying 
the units.
For a unit string $ustr$:
o ' $ustr$' (with one or more preceeding spaces) denotes multiplied by $ustr$
o '/$ustr$' denotes divided by $ustr$
o '$ustr$**y denotes $ustr$ raised to the power y

However, to minimize the risk of ambiguities, and to simplify the task of 
parsing the whole string giving the compound unit, the following rules are 
also required:
- all the multiplicative units within the compound unit should be specified 
  first
- all units which are being divided by should have a preceeding '/' (slash)
- raising units to a negative power should not be used, 
  hence '/$ustr$**z should be used rather than '$ustr$**-z (for z>0)

COMMENTS SO FAR
---------------

1) Bill Pence suggests: 
	that multiplicative units should be separated by an * (asterix)
	eg 	m * s /Hz 	for metre seconds per hertz

2) Paul Barrett suggests:
	a) the promotion of eV to Table 2, 
	b) the demotion of keV to Table 3, 
	c) the inclusion of GeV in Table 3

---

From: Lucio Chiappetti <[email-masked]>
Date: Thu, 15 Apr 93 12:59:08 -0400

Sorry Ian, your Postscript file looks ... unviewable. I did not even try
to print it, I just looked at it with a previewer and gave me an offending
command close to the beginning :

%%BeginSetup
BeginDviLaserDoc
300 300 RES
%%EndSetup

It looks like you call some external file or procedure  which obviously
defines some macros which are unknown to my previewer (DEC CDA Viewer).
If you could perhaps make such macros available, perhaps anybody could
then print the file.
It looks quite strange to me anyhow (lot of binary stuff).

I usually produce Postscript file from a Mac, in such case there is a
HUGE printer-dependent prolog on top of the file, which makes the file
very large, but as far as I know anybody could print it also on non-Apple
printers.
(Usually the problems I have encountered so far in exporting .ps files
were due to the fact there were VMS machines at the other end. They often
get confused by a file with very long records. Usually the trick is to
ftp-binary the file onto a Vax : this forces records to 512 - which is
manageable - while leaving the content intact and usable also by Unix
machines. Of course this has nothing to do with the problem of YOUR file)

-----------------------------------------------------------------------------
       A member of  G.ASS : Group for Astronomical Software Support
-----------------------------------------------------------------------------
Lucio Chiappetti - IFCTR/CNR Milano        |         U N I C U I Q U E
via Bassini 15 - I-20133 Milano - Italy    |          System  Manager
Internet: [email-masked]            |           FORTUNAE SUAE
Decnet:   IFCTR::LUCIO (39610::LUCIO)      |
Bitnet:   <please do not use any more>     |
-----------------------------------------------------------------------------