ZTOOLS Vectors - tomographic tools

(Design documents....)

Craig DeForest
Last update: 6-Oct-97

Contents

Introduction    (Contents)

We need a set of tools for manipulating three- and four- vectors. Ideally, the most common three-vector co-ordinate systems (in solar physics) should be available and easily interconvertible.

Luckily, we only live in four-space, so it should be relatively simple to keep four numbers and some co-ordinate information in a structure. Unluckily, the common ways of measuring time are completely opaque, compared to our common ways of measuring angle and distance.

Further, some co-ordinate systems are rotating or moving with respect to others; so it's important (in most cases) to keep track not only of what time it is; but also of whether we know what time it is. Because I really really like the ability to have undefined variables, and because IDL doesn't have a good system for handling them (compare perl's system), I'd also like to keep track of whether each of our four co-ordinates is defined.

The time business isn't a show-stopper, but I think it precludes storing the variables as a single four-array. And I don't like treating a particular co-ordinate differently than the others -- at least, not on this deep level. So I think the four co-ordinates should be independent variables. That way, we can redefine their types dynamically.

To that end, here're some design documents for a set of routines to handle vectors in four-space:

Data Structures    (Contents)

We need a bunch of data structures to describe 4-vectors. However, rather than naming the structures explicitly I usually am leaving them anonymous. That's to reduce type-checking conflicts. Each of them, however, has a name. Here they are:

V4   (Contents)

Here's a four-vector. The order of the tags matters. The standard way to generate a four-vector is to call V4(), which stuffs some co-ordinates into a standard four-vector structure, then returns it. 

V4 =  	{x0		:"1-Jan-1997 00:00:00 UT"		$
		,x1		:0d0					$
		,x2		:0d0					$
		,x3		:0d0					$
		,coords		:"Heliographic"				$
		,u0		:"Timestamp"				$
		,u1		:"degrees"				$
		,u2		:"degrees"				$
		,u3		:"solar-radii"				$
		,defined	:replicate(1,4)				$
		,ext		:foo_extra				$
		}

The first four elements of the structure are the four co-ordinates, stuffed into different variables rather than a single array so that they can be of different types (eg the time co-ordinate here is different than the spatial ones.)

The "system" tag comes immediately after the co-ordinates, and is a string containing one of a few prescribed co-ordinate systems. A routine should exist that accepts a co-ordinate system name and spouts out strings that identify the meanings of the co-ordinates.

The following four tags (u0-u3) are strings that specify the units in which each co-ordinate is given. The strings should be units that are recognizable by ZUNITS, with the exception of "TIMESTAMP" -- times need more careful conversion than zunits can provide.

The "defined" tag should only be present if all other nine tags are present. It should be an array of flags indicating which of the other tags actually being specified. This provides a way of recording, for example, positions taken from images -- where the distance along the line of sight isn't known.

The "ext" tag allows additional information about the coordinate system to be inserted. In particular, it allows naming of specific coordinate systems without their individual incorporation into the system. (One may name a generic "local Cartesian" coordinate system with reference to one of the other systems, for example).

Here's a tentative plan for the use of the "ext" tag: 

ext = {foo_extra							$
      ,ID         :"Name-of-general-coordinate-system"			$
      ,origin     :v4_origin						$
      ,orientation:matrix						$
	}
	




V4TYPE
   (Contents)


We need to keep track of four-vector types somehow.  The master template
for four-vectors is given in define_v4types.pro.  Here's a sample v4type structure (which IS named...)

v4type = {v4type						      		$
	 ,coords:["Carrington","C","",""]				      	$
	 ,units: ["timestamp",	"deg",		"deg",		"solar-radii"]	$
	 ,udesc: ["time",	"C-Longitude",	"Latitude",	"above Sun ctr"]$
	 ,desc:"Pole at Solar North; prime meridian spinning with equator"	$
	 ,metric:"v4m_sph",  index:[0,1,2,3]					$
	}




The "coords" tag is an array of four strings (up to 30 characters each) containing
alternate names for the co-ordinate system.  


The "units" tag is an array of four unit strings describing the canonical units in
which the coordinates should be expressed.  In fact, any equivalent unit will do
(for example, if the v4type unit for x1 is "deg", one may specify one's actual 
x1 coordinate in "arcsec" but not in "km".  The former is a unit of angle like
"deg", while the latter is a unit of distance.)


The "udesc" tag is an array of four strings containing very brief descriptions
of each co-ordinate in the system (eg "Longitude", etc.)


The "desc" tag contains a string with a one-line description of the coordinate
sytem as a whole.


The "metric" and "index" tags point to a metric function that returns the distance between
two points in this coordinate system.  The "index" array of four elements indicates the
order in which the coordinates should be presented to the metric routine, so that 
metric routines may be re-used.  If the "metric" tag begins with "convert to ", then
metrics are measured by conversion to another coordinate system (eg "convert to HC") means
to convert to heliographic cartesian coordinates and take metrics in that system.


V4XFORM
   (Contents)


 The V4XFORM structure keeps track of the way to convert between two coordinate 
systems.  It needs to be sort-of general:  many "families" of co-ordinate systems
will exist whose relationships can be parametrized rather than separately 
coded.  (for example, "Heliographic" : "Heliographic Cartesian" :: "Solar" : "Solar Cartesian").  So we should store a procedure 
name for the conversion and a pair of 4-arrays that order the indices of the
incoming and outgoing co-ordinates.  We also should store a "compound path" that
can be superseded by the method/index/outdex/parameter information -- so that we
can generate compound conversion methods on-the-fly.


 Conversions between coordinate systems are handled by method functions that take a standard set of inputs and generate a standard set of results.


 For now, compound_array has 15 entries, each of which is either "" or the name
of a subsequent coordinate system starting with the "from:" system and ending with
the "to:" system.


compound_array=replicate("",15)
v4xform={v4xform
	,from:"heliographic",	to:"heliographic cartesian"
	,method:"v4sph2cart",	index:[0,1,2,3],	outdex:[0,1,2,3]
	,compound:compound_array
	}

	






Coordinate systems to be recognized
   (Contents)


 There are six systems that are useful to start with: the
Solar, Heliographic, and Carrington spherical systems; and their three
equivalent cartesian systems.  Five of the systems have origins at Sun
Center; one ("Solar coordinates") does not.


ERS (Earth-Range Solar)

	Earth-based spherical (SoHO's "Solar Coordinates"). Note that SoHO's
instruments can't resolve the parallax between SoHO and the Earth, but that
future instruments may be able to; we need to extend this definition...)
The reference ``north'' is solar north, projected into the plane perpendicular
to the Earth-Sun line.

X0:	time
X1:	Angle west from disk center as seen from Earth
X2:	Angle north from disk center as seen from Earth
X3: 	Distance from Earth 




SRS (Solar-Range Solar)

	SoHO's ``Solar coordinates'' (see ERS) except that the range 
coordinate (x3; ``Z'' coordinate) is radius above Sun center.

X0:	time
X1: 	Angle west from disk center as seen from Earth
X2:	Angle north from disk center as seen from Earth
X3:	Distance from Earth




ESC (Earth-Solar Cartesian; SC; Solar Cartesian)

Cartesian approximation to "SRS" coordinates.  The 
``X-Y'' plane is determined by the Sun's axis on the solar disk
as seen from Earth.  Origin at Sun center.
The ``Z'' direction is straight toward the Earth from the Sun.

X0:	time
X1:	"West"  as seen from Earth (perpendicular to X2 & X3)
X2:	"North" as seen from Earth (coplanar with Solar North)
X3:	Toward the Earth




GSE (Geocentric Solar Ecliptic; GSEC; Geocentric Solar Ecliptic Cartesian)

Similar to ESC, but oriented to the ecliptic pole rather than the
solar pole. Matches SOHO orbit file GSE.  Not yet implemented

X0: 	time
X1:	Points from Earth to the center of the Sun
X2:	Antiparallel to Earth's orbital motion in the ecliptic
X3:	Parallel to the ecliptic pole




GSM (Geocentric Solar Magnetospheric


Heliographic

Spherical system oriented on the Sun's axis, with the prime 
meridian of longitude containing the Earth (non-inertial).

X0:	time
X1:	Longitude	(angle west (Solar east) of central meridian)
X2:	Latitude	(angle relative to equator)
X3:	Radius		(distance fron Sun center)




HC (Heliographic Cartesian)

Cartesian system embedded in heliographic co-ordinates.  

X0:	time
X1:	Out the equator in the westward (as seen from Earth) direction
X2:	Solar North
X3:	Out the equator through the central meridian (almost toward Earth)




Carrington



X0:	time
X1:	Longitude	(east (west as seen from Earth) from prime meridian)
X2:	Latitude	(northward angle relative to equator)
X3:	Radius		(distance from Sun center)




CC (Carrington Cartesian) 

 Cartesian system anchored in the rotating Carrington frame (with origin
at Sun Center).

X0:	time
X1:  	Out the equator through the 90-degree-East Carrington meridian.
X2:	Solar North
X3:	Out the equator through the prime Carrington meridian.




GCI (GeoCentric Inertial; Geocentric Inertial Cartesian; GIC)

 Origin is at Earth; ``X'' Axis points toward first point of Aries.  The
``Z'' axis is parallel to the Earth's rotation axis, and the ``Y'' axis is 
perpendicular to both.  Matches SOHO Orbit files' GCI system.

Not yet implemented.




HEC (Heliocentric Ecliptic; Heliocentric Ecliptic Cartesian)

 Cartesian system. Origin at center of Sun; Z axis parallel to the 
ecliptic pole; X-Y plane lies in the ecliptic plane with X pointing 
toward Aries.

Not yet implemented.








Procedures & Functions
   (Contents)





Metric functions




Metric functions take two V4 vectors as input, and return a distance.  Because,
most of the time, people want to work with 3-vectors, metric functions work in 3-space
by default; but they take a flag ("DIM") that allows you to switch between different
dimensionalities.  In general, 2-dimensional distances "look" like they would in the 
image plane of a telescope (eg spherical coordinates give great circle arc angles); 
3-dimensional distances "look" like regular 3-space distances (with some caveats; see
the next paragraph); and 4-dimensional distances are the familiar relativistic invariants.


 
Some caveats exist for the 2- and 3- space distances.  Because the 2-distances are defined
differently for different coordinate systems, and because some of the coordinate systems
are in motion with respect to one another, you can get in serious trouble by mixing coordinate
systems without thinking.  


 
The non-relativistic metrics assume that both points are stationary within their respective
coordinate systems, and make their measurements in the first coordinate system.  That is
to say, if A and B are V4 vectors in Carrington coordinates, and their 3-vector parts are
identical but their times differ, then 

	v4metric(A,B,dim=3)

 and 

	v4metric(v4xform(A,'solar'),v4xform(B,'solar'),dim=3)

 will yield 
the same number -- 0.   But 

	v4metric(v4xform(A,'solar'),B,dim=3)

 will return a 
nonzero value, because A is now held fixed in the solar coordinate system, while B is
held fixed in the Carrington coordinate system.  The two systems are in motion with respect
to each other.




Here's a prototype interface for a typical metric function:

;+
; NAME:
;	V4MCART
; PURPOSE:
;	Return the distance between two points in a cartesian coordinate system.
;	(normally called by V4METRIC based on the v4type structure)
; CALLING SEQUENCE:
;	out = V4MCART(in1,in2,/verbose,index=ix,units=units,four=four)
; INPUTS:
;	in1, in2 - V4 structures containing the co-ordinates to measure
; RETURNS:
;	The distance between the two points
; KEYWORDS: 
;	VERBOSE - Be chatty
;	INDEX   - A 4-array that re-orders the input vectors
;	UNITS   - If present, V4MCART attempts to return a value in the units given.
;		  If not defined, V4MCART sets this to the name of the units in which the
;		  value is returned.
;	DIM     - Flag indicating the number of dimensions to use in the process.
;-









Method functions



These are used to convert between individual, well-known coordinate systems.
You supply a v4 input vector and get back a v4 output vector. 
Here's an example interface from a typical method function.




;+
; NAME:
;	V4XSPH2CART
; PURPOSE:
;	Convert Spherical to associated Cartesian coordinates
;	(normally called by V4XFORM based on the v4xforms structure)
; CALLING SEQUENCE:
;	out = V4XSPH2CART(in,/verbose,index=ix,outdex=ox,ocoord=ocoord)
; INPUTS:
;	in - a V4 structure containing the spherical co-ordinates to 
;	     transform to Cartesian
; RETURNS:
;	The transformed vector (or array)
; KEYWORDS:
;	VERBOSE - Be chatty
;	INDEX   - A 4-array that re-orders the input vector
;	OUTDEX  - A 4-array that re-orders the output vector
;	OCOORD  - The coordinate system name for the output coordinates 
;-