G Using MathMaps

 G.1 Defining Transformation Functions
 G.2 Calculating Intermediate Values
 G.3 Expression Syntax
 G.4 Variables
 G.5 Literal Constants
 G.6 Arithmetic Precision
 G.7 Propagation of Missing Data
 G.8 Arithmetic Operators
 G.9 Logical Operators
 G.10 Relational Operators
 G.11 Bitwise Operators
 G.12 Functions
 G.13 Symbolic Constants
 G.14 Evaluation Precedence and Associativity

A MathMap is an AST Object which contains a recipe for transforming positions from one co-ordinate Frame  to another and (optionally) back again. These transformations are specified using arithmetic operations and mathematical functions similar to those available in Fortran. WCSADD can be used to create a MathMap and store it in a text file, and such text files can then be used by applications such as REGRID which require a mapping.

G.1 Defining Transformation Functions

A MathMap’s transformation functions are defined by a set of character strings holding Fortran-like expressions. If the required Mapping has Nin input axes and Nout output axes, you would normally supply the Nout expressions for the forward transformation. For instance, if Nout is 2 you might use:

        ’R = SQRT( X * X + Y * Y )’
        ’THETA = ATAN2( Y, X )’

which defines a transformation from Cartesian to polar co-ordinates. Here, the variables that appear on the left of each expression (R and THETA) provide names for the output variables and those that appear on the right (X and Y) are references to input variables.

To complement this, you must also supply expressions for the inverse transformation. In this case, the number of expressions given would normally match the number of MathMap input co-ordinates, Nin. If Nin is 2, you might use:

        ’X = R $*$ COS( THETA )’
        ’Y = R $*$ SIN( THETA )’

which expresses the transformation from polar to Cartesian co-ordinates. Note that here the input variables (X and Y) are named on the left of each expression, and the output variables (R and THETA) are referenced on the right.

Normally, you cannot refer to a variable on the right of an expression unless it is named on the left of an expression in the complementary set of functions. Therefore both sets of functions (forward and inverse) must be formulated using the same consistent set of variable names. This means that if you wish to leave one of the transformations undefined, you must supply dummy expressions which simply name each of the output (or input) variables. For example, you might use:

        ’X’
        ’Y’

for the inverse transformation above, which serves to name the input variables but without defining an inverse transformation.

G.2 Calculating Intermediate Values

It is sometimes useful to calculate intermediate values and then to use these in the final expressions for the output (or input) variables. This may be done by supplying additional expressions for the forward (or inverse) transformation functions. For instance, the following array of five expressions describes two-dimensional pin-cushion distortion:

           ’R = SQRT( XIN $*$ XIN $+$ YIN $*$ YIN )’
           ’ROUT = R $*$ ( 1 $+$ 0.1 $*$ R $*$ R )’
           ’THETA = ATAN2( YIN, XIN )’,
           ’XOUT = ROUT $*$ COS( THETA )’
           ’YOUT = ROUT $*$ SIN( THETA )’

Here, we first calculate three intermediate results (R, ROUT and THETA) and then use these to calculate the final results (XOUT and YOUT). The MathMap knows that only the final two results constitute values for the output variables because its Nout attribute is set to 2. You may define as many intermediate variables in this way as you choose. Having defined a variable, you may then refer to it on the right of any subsequent expressions.

Note that when defining the inverse transformation you may only refer to the output variables XOUT and YOUT. The intermediate variables R, ROUT and THETA (above) are private to the forward transformation and may not be referenced by the inverse transformation. The inverse transformation may, however, define its own private intermediate variables.

G.3 Expression Syntax

The expressions given for the forward and inverse transformations closely follow the syntax of Fortran (with some extensions for compatibility with the C language). They may contain references to variables and literal constants, together with arithmetic, logical, relational and bitwise operators, and function invocations. A set of symbolic constants is also available. Each of these is described in detail below. Parentheses may be used to override the normal order of evaluation. There is no built-in limit to the length of expressions and they are insensitive to case or the presence of additional white space.

G.4 Variables

Variable names must begin with an alphabetic character and may contain only alphabetic characters, digits, and the underscore character "_". There is no built-in limit to the length of variable names.

G.5 Literal Constants

Literal constants, such as "0", "1", "0.007" or "2.505E-16" may appear in expressions, with the decimal point and exponent being optional (a "D" may also be used as an exponent character). A unary minus "-" may be used as a prefix.

G.6 Arithmetic Precision

All arithmetic is floating point, performed in double precision.

G.7 Propagation of Missing Data

Unless indicated otherwise, if any argument of a function or operator has a bad value (indicating missing data), then the result of that function or operation is also bad, so that such values are propagated automatically through all operations performed by MathMap transformations. The special value used to flag bad values can be represented in expressions by the symbolic constant " <bad >".

A <bad > result is also produced in response to any numerical error (such as division by zero or numerical overflow), or if an invalid argument value is provided to a function or operator.

G.8 Arithmetic Operators

The following arithmetic operators are available:

G.9 Logical Operators

Logical values are represented using zero to indicate .FALSE. And non-zero to indicate .TRUE.. In addition, the bad value is taken to mean "unknown". The values returned by logical operators may therefore be 0, 1 or bad. Where appropriate, "tri-state" logic is implemented. For example, A.OR.B may evaluate to 1 if A is non-zero, even if B has the bad value. This is because the result of the operation would not be affected by the value of B, so long as A is non-zero.

The following logical operators are available:

G.10 Relational Operators

Relational operators return the logical result (0 or 1) of comparing the values of two floating-point values for equality or inequality. The bad value may also be returned if either argument is <bad >.

The following relational operators are available:

Note that relational operators cannot usefully be used to compare values with the <bad > value (representing missing data), because the result is always <bad >. The ISBAD() function should be used instead.

Note, also, that because logical operators can operate on floating point values, care must be taken to use parentheses in some cases where they would not normally be required in Fortran. For example, the expression:

           .NOT.  A .EQ. B

must be written:

           .NOT. ( A .EQ. B )

to prevent the .NOT. Operator from associating with the variable A.

G.11 Bitwise Operators

Bitwise operators are often useful when operating on raw data (e.g. from instruments), so they are provided for use in MathMap expressions. In this case, however, the values on which they operate are floating-point values rather than the more usual pure integers. In order to produce results which match the pure integer case, the operands are regarded as fixed point binary numbers (i.e. with the binary equivalent of a decimal point) with negative numbers represented using twos-complement notation. For integer values, the resulting bit pattern corresponds to that of the equivalent signed integer (digits to the right of the point being zero). Operations on the bits representing the fractional part are also possible, however.

The following bitwise operators are available:

Note that no bit inversion operator is provided. This is because inverting the bits of a twos-complement fixed point binary number is equivalent to simply negating it. This differs from the pure integer case because bits to the right of the binary point are also inverted. To invert only those bits to the left of the binary point, use a bitwise exclusive OR with the value -1 (i.e. X^-1).

G.12 Functions

The following functions are available:

G.13 Symbolic Constants

The following symbolic constants are available (the enclosing " < >" brackets must be included):

G.14 Evaluation Precedence and Associativity

Items appearing in expressions are evaluated in the following order (highest precedence first):

All operators associate from left-to-right, except for unary +, unary -, !, .not. And which associate from right-to-left.