uk.ac.starlink.ast
Class MathMap

java.lang.Object
  extended by uk.ac.starlink.ast.AstObject
      extended by uk.ac.starlink.ast.Mapping
          extended by uk.ac.starlink.ast.MathMap

public class MathMap
extends Mapping

Java interface to the AST MathMap class - transform coordinates using mathematical expressions. A MathMap is a Mapping which allows you to specify a set of forward and/or inverse transformation functions using arithmetic operations and mathematical functions similar to those available in C. The MathMap interprets these functions at run-time, whenever its forward or inverse transformation is required. Because the functions are not compiled in the normal sense (unlike an IntraMap), they may be used to describe coordinate transformations in a transportable manner. A MathMap therefore provides a flexible way of defining new types of Mapping whose descriptions may be stored as part of a dataset and interpreted by other programs.

Licence

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public Licence as published by the Free Software Foundation; either version 2 of the Licence, or (at your option) any later version.

This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public Licence for more details.

You should have received a copy of the GNU General Public Licence along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street,Fifth Floor, Boston, MA 02110-1301, USA

See Also:
AST MathMap

Nested Class Summary
 
Nested classes/interfaces inherited from class uk.ac.starlink.ast.Mapping
Mapping.Interpolator, Mapping.Spreader
 
Field Summary
 
Fields inherited from class uk.ac.starlink.ast.Mapping
LINEAR_INTERPOLATOR, LINEAR_SPREADER, NEAREST_INTERPOLATOR, NEAREST_SPREADER
 
Fields inherited from class uk.ac.starlink.ast.AstObject
AST__BAD, AST__TUNULL, pointer
 
Constructor Summary
MathMap(int nin, int nout, String[] fwd, String[] inv)
          Create a MathMap.
 
Method Summary
 int getSeed()
          Get random number seed for a MathMap.
 boolean getSimpFI()
          Get forward-inverse MathMap pairs simplify.
 boolean getSimpIF()
          Get inverse-forward MathMap pairs simplify.
 void setSeed(int seed)
          Set random number seed for a MathMap.
 void setSimpFI(boolean simpFI)
          Set forward-inverse MathMap pairs simplify.
 void setSimpIF(boolean simpIF)
          Set inverse-forward MathMap pairs simplify.
 
Methods inherited from class uk.ac.starlink.ast.Mapping
decompose, getInvert, getNin, getNout, getReport, getTranForward, getTranInverse, invert, linearApprox, mapBox, mapSplit, rate, rebin, rebinD, rebinF, rebinI, resample, resampleB, resampleD, resampleF, resampleI, resampleL, resampleS, setInvert, setReport, simplify, tran1, tran2, tranGrid, tranN, tranP
 
Methods inherited from class uk.ac.starlink.ast.AstObject
annul, clear, copy, delete, equals, finalize, getAstConstantI, getB, getC, getD, getF, getI, getID, getIdent, getL, getNobject, getObjSize, getRefCount, hashCode, isThreaded, reportVersions, sameObject, set, setB, setC, setD, setF, setI, setID, setIdent, setL, show, test, tune
 
Methods inherited from class java.lang.Object
clone, getClass, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MathMap

public MathMap(int nin,
               int nout,
               String[] fwd,
               String[] inv)
Create a MathMap. This function creates a new MathMap and optionally initialises its attributes.

A MathMap is a Mapping which allows you to specify a set of forward and/or inverse transformation functions using arithmetic operations and mathematical functions similar to those available in C. The MathMap interprets these functions at run-time, whenever its forward or inverse transformation is required. Because the functions are not compiled in the normal sense (unlike an IntraMap), they may be used to describe coordinate transformations in a transportable manner. A MathMap therefore provides a flexible way of defining new types of Mapping whose descriptions may be stored as part of a dataset and interpreted by other programs.

Defining Transformation Functions

A MathMap's transformation functions are supplied as a set of expressions in an array of character strings. Normally you would supply the same number of expressions for the forward transformation, via the "fwd" parameter, as there are output variables (given by the MathMap's Nout attribute). 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 coordinates. 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 via the "inv" parameter. In this case, the number of expressions given would normally match the number of MathMap input coordinates (given by the Nin attribute). If Nin is 2, you might use:
- "x = r * cos( theta )"
- "y = r * sin( theta )"

which expresses the transformation from polar to Cartesian coordinates. 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.

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 2-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.

Expression Syntax

The expressions given for the forward and inverse transformations closely follow the syntax of the C programming language (with some extensions for compatibility with Fortran). They may contain references to variables and literal constants, together with arithmetic, boolean, 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 over-ride 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.

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.

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 for compatibility with Fortran). A unary minus "-" may be used as a prefix.

Arithmetic Precision

All arithmetic is floating point, performed in double precision.

Propagation of Missing Data

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

A result (i.e. equal to AST__BAD) 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.

Arithmetic Operators

The following arithmetic operators are available:
- x1 + x2: Sum of "x1" and "x2".
- x1 - x2: Difference of "x1" and "x2".
- x1 * x2: Product of "x1" and "x1".
- x1 / x2: Ratio of "x1" and "x2".
- x1 ** x2: "x1" raised to the power of "x2".
- + x: Unary plus, has no effect on its argument.
- - x: Unary minus, negates its argument.

Boolean Operators

Boolean values are represented using zero to indicate false and non-zero to indicate true. In addition, the value AST__BAD is taken to mean "unknown". The values returned by boolean operators may therefore be 0, 1 or AST__BAD. Where appropriate, "tri-state" logic is implemented. For example, "a||b" may evaluate to 1 if "a" is non-zero, even if "b" has the value AST__BAD. 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 boolean operators are available:
- x1 && x2: Boolean AND between "x1" and "x2", returning 1 if both "x1" and "x2" are non-zero, and 0 otherwise. This operator implements tri-state logic. (The synonym ".and." is also provided for compatibility with Fortran.)
- x1 || x2: Boolean OR between "x1" and "x2", returning 1 if either "x1" or "x2" are non-zero, and 0 otherwise. This operator implements tri-state logic. (The synonym ".or." is also provided for compatibility with Fortran.)
- x1 ^^ x2: Boolean exclusive OR (XOR) between "x1" and "x2", returning 1 if exactly one of "x1" and "x2" is non-zero, and 0 otherwise. Tri-state logic is not used with this operator. (The synonyms ".neqv." and ".xor." are also provided for compatibility with Fortran, although the second of these is not standard.)
- x1 .eqv. x2: This is provided only for compatibility with Fortran and tests whether the boolean states of "x1" and "x2" (i.e. true/false) are equal. It is the negative of the exclusive OR (XOR) function. Tri-state logic is not used with this operator.
- ! x: Boolean unary NOT operation, returning 1 if "x" is zero, and 0 otherwise. (The synonym ".not." is also provided for compatibility with Fortran.)

Relational Operators

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

The following relational operators are available:
- x1 == x2: Tests whether "x1" equals "x1". (The synonym ".eq." is also provided for compatibility with Fortran.)
- x1 != x2: Tests whether "x1" is unequal to "x2". (The synonym ".ne." is also provided for compatibility with Fortran.)
- x1 > x2: Tests whether "x1" is greater than "x2". (The synonym ".gt." is also provided for compatibility with Fortran.)
- x1 >= x2: Tests whether "x1" is greater than or equal to "x2". (The synonym ".ge." is also provided for compatibility with Fortran.)
- x1 < x2: Tests whether "x1" is less than "x2". (The synonym ".lt." is also provided for compatibility with Fortran.)
- x1 <= x2: Tests whether "x1" is less than or equal to "x2". (The synonym ".le." is also provided for compatibility with Fortran.)

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

Bitwise Operators

The bitwise operators provided by C are often useful when operating on raw data (e.g. from instruments), so they are also provided for use in MathMap expressions. In this case, however, the values on which they operate are floating point values rather than 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:
- x1 >> x2: Rightward bit shift. The integer value of "x2" is taken (rounding towards zero) and the bits representing "x1" are then shifted this number of places to the right (or to the left if the number of places is negative). This is equivalent to dividing "x1" by the corresponding power of 2.
- x1 << x2: Leftward bit shift. The integer value of "x2" is taken (rounding towards zero), and the bits representing "x1" are then shifted this number of places to the left (or to the right if the number of places is negative). This is equivalent to multiplying "x1" by the corresponding power of 2.
- x1 & x2: Bitwise AND between the bits of "x1" and those of "x2" (equivalent to a boolean AND applied at each bit position in turn).
- x1 | x2: Bitwise OR between the bits of "x1" and those of "x2" (equivalent to a boolean OR applied at each bit position in turn).
- x1 ^ x2: Bitwise exclusive OR (XOR) between the bits of "x1" and those of "x2" (equivalent to a boolean XOR applied at each bit position in turn).

Note that no bit inversion operator ("~" in C) 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").

Symbolic Constants

The following symbolic constants are available (the enclosing "<>" brackets must be included):
- : The "bad" value (AST__BAD) used to flag missing data. Note that you cannot usefully compare values with this constant because the result is always . The isbad() function should be used instead.
- : Number of decimal digits of precision available in a floating point (double) value.
- : Base of natural logarithms.
- : Smallest positive number such that 1.0+ is distinguishable from unity.
- : The number of base digits stored in the mantissa of a floating point (double) value.
- : Maximum representable floating point (double) value.
- : Maximum integer such that 10 raised to that power can be represented as a floating point (double) value.
- : Maximum integer such that raised to that power minus 1 can be represented as a floating point (double) value.
- : Smallest positive number which can be represented as a normalised floating point (double) value.
- : Minimum negative integer such that 10 raised to that power can be represented as a normalised floating point (double) value.
- : Minimum negative integer such that raised to that power minus 1 can be represented as a normalised floating point (double) value.
- : Ratio of the circumference of a circle to its diameter.
- : The radix (number base) used to represent the mantissa of floating point (double) values.
- : The mode used for rounding floating point results after addition. Possible values include: -1 (indeterminate), 0 (toward zero), 1 (to nearest), 2 (toward plus infinity) and 3 (toward minus infinity). Other values indicate machine-dependent behaviour.

Evaluation Precedence and Associativity

Items appearing in expressions are evaluated in the following order (highest precedence first):
- Constants and variables
- Function arguments and parenthesised expressions
- Function invocations
- Unary + - ! .not.
- **
- * /
- + -
- << >>
- < .lt. <= .le. > .gt. >= .ge.
- == .eq. != .ne.
- &
- ^
- |
- && .and.
- ^^
- || .or
- .eqv. .neqv. .xor.

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

Notes


- The sequence of numbers produced by the random number functions available within a MathMap is normally unpredictable and different for each MathMap. However, this behaviour may be controlled by means of the MathMap's Seed attribute.
- Normally, compound Mappings (CmpMaps) which involve MathMaps will not be subject to simplification (e.g. using astSimplify) because AST cannot know how different MathMaps will interact. However, in the special case where a MathMap occurs in series with its own inverse, then simplification may be possible. Whether simplification does, in fact, occur under these circumstances is controlled by the MathMap's SimpFI and SimpIF attributes.
- A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason.

Parameters:
nin - Number of input variables for the MathMap. This determines the value of its Nin attribute.
nout - Number of output variables for the MathMap. This determines the value of its Nout attribute.
fwd - an array of Strings describing the forward transformations. There should be at least nout of these, but there may be more (see the note on "Calculating intermediate values").
inv - an array of Strings describing the inverse transformations. There should be at least nin of these, but there may be more (see the note on "Calculating intermediate values").
Throws:
AstException - if an error occurred in the AST library
Method Detail

getSeed

public int getSeed()
Get random number seed for a MathMap. This attribute, which may take any integer value, determines the sequence of random numbers produced by the random number functions in MathMap expressions. It is set to an unpredictable default value when a MathMap is created, so that by default each MathMap uses a different set of random numbers.

If required, you may set this Seed attribute to a value of your choosing in order to produce repeatable behaviour from the random number functions. You may also enquire the Seed value (e.g. if an initially unpredictable value has been used) and then use it to reproduce the resulting sequence of random numbers, either from the same MathMap or from another one.

Clearing the Seed attribute gives it a new unpredictable default value.

Returns:
this object's Seed attribute

setSeed

public void setSeed(int seed)
Set random number seed for a MathMap. This attribute, which may take any integer value, determines the sequence of random numbers produced by the random number functions in MathMap expressions. It is set to an unpredictable default value when a MathMap is created, so that by default each MathMap uses a different set of random numbers.

If required, you may set this Seed attribute to a value of your choosing in order to produce repeatable behaviour from the random number functions. You may also enquire the Seed value (e.g. if an initially unpredictable value has been used) and then use it to reproduce the resulting sequence of random numbers, either from the same MathMap or from another one.

Clearing the Seed attribute gives it a new unpredictable default value.

Parameters:
seed - the Seed attribute of this object

getSimpFI

public boolean getSimpFI()
Get forward-inverse MathMap pairs simplify. This attribute should be set to a non-zero value if applying a MathMap's forward transformation, followed immediately by the matching inverse transformation will always restore the original set of coordinates. It indicates that AST may replace such a sequence of operations by an identity Mapping (a UnitMap) if it is encountered while simplifying a compound Mapping (e.g. using astSimplify).

By default, the SimpFI attribute is zero, so that AST will not perform this simplification unless you have set SimpFI to indicate that it is safe to do so.

Notes


- For simplification to occur, the two MathMaps must be in series and be identical (with textually identical transformation functions). Functional equivalence is not sufficient.
- The consent of both MathMaps is required before simplification can take place. If either has a SimpFI value of zero, then simplification will not occur.
- The SimpFI attribute controls simplification only in the case where a MathMap's forward transformation is followed by the matching inverse transformation. It does not apply if an inverse transformation is followed by a forward transformation. This latter case is controlled by the SimpIF attribute.
- The "forward" and "inverse" transformations referred to are those defined when the MathMap is created (corresponding to the "fwd" and "inv" parameters of its constructor function). If the MathMap is inverted (i.e. its Invert attribute is non-zero), then the role of the SimpFI and SimpIF attributes will be interchanged.

Returns:
this object's SimpFI attribute

setSimpFI

public void setSimpFI(boolean simpFI)
Set forward-inverse MathMap pairs simplify. This attribute should be set to a non-zero value if applying a MathMap's forward transformation, followed immediately by the matching inverse transformation will always restore the original set of coordinates. It indicates that AST may replace such a sequence of operations by an identity Mapping (a UnitMap) if it is encountered while simplifying a compound Mapping (e.g. using astSimplify).

By default, the SimpFI attribute is zero, so that AST will not perform this simplification unless you have set SimpFI to indicate that it is safe to do so.

Notes


- For simplification to occur, the two MathMaps must be in series and be identical (with textually identical transformation functions). Functional equivalence is not sufficient.
- The consent of both MathMaps is required before simplification can take place. If either has a SimpFI value of zero, then simplification will not occur.
- The SimpFI attribute controls simplification only in the case where a MathMap's forward transformation is followed by the matching inverse transformation. It does not apply if an inverse transformation is followed by a forward transformation. This latter case is controlled by the SimpIF attribute.
- The "forward" and "inverse" transformations referred to are those defined when the MathMap is created (corresponding to the "fwd" and "inv" parameters of its constructor function). If the MathMap is inverted (i.e. its Invert attribute is non-zero), then the role of the SimpFI and SimpIF attributes will be interchanged.

Parameters:
simpFI - the SimpFI attribute of this object

getSimpIF

public boolean getSimpIF()
Get inverse-forward MathMap pairs simplify. This attribute should be set to a non-zero value if applying a MathMap's inverse transformation, followed immediately by the matching forward transformation will always restore the original set of coordinates. It indicates that AST may replace such a sequence of operations by an identity Mapping (a UnitMap) if it is encountered while simplifying a compound Mapping (e.g. using astSimplify).

By default, the SimpIF attribute is zero, so that AST will not perform this simplification unless you have set SimpIF to indicate that it is safe to do so.

Notes


- For simplification to occur, the two MathMaps must be in series and be identical (with textually identical transformation functions). Functional equivalence is not sufficient.
- The consent of both MathMaps is required before simplification can take place. If either has a SimpIF value of zero, then simplification will not occur.
- The SimpIF attribute controls simplification only in the case where a MathMap's inverse transformation is followed by the matching forward transformation. It does not apply if a forward transformation is followed by an inverse transformation. This latter case is controlled by the SimpFI attribute.
- The "forward" and "inverse" transformations referred to are those defined when the MathMap is created (corresponding to the "fwd" and "inv" parameters of its constructor function). If the MathMap is inverted (i.e. its Invert attribute is non-zero), then the role of the SimpFI and SimpIF attributes will be interchanged.

Returns:
this object's SimpIF attribute

setSimpIF

public void setSimpIF(boolean simpIF)
Set inverse-forward MathMap pairs simplify. This attribute should be set to a non-zero value if applying a MathMap's inverse transformation, followed immediately by the matching forward transformation will always restore the original set of coordinates. It indicates that AST may replace such a sequence of operations by an identity Mapping (a UnitMap) if it is encountered while simplifying a compound Mapping (e.g. using astSimplify).

By default, the SimpIF attribute is zero, so that AST will not perform this simplification unless you have set SimpIF to indicate that it is safe to do so.

Notes


- For simplification to occur, the two MathMaps must be in series and be identical (with textually identical transformation functions). Functional equivalence is not sufficient.
- The consent of both MathMaps is required before simplification can take place. If either has a SimpIF value of zero, then simplification will not occur.
- The SimpIF attribute controls simplification only in the case where a MathMap's inverse transformation is followed by the matching forward transformation. It does not apply if a forward transformation is followed by an inverse transformation. This latter case is controlled by the SimpFI attribute.
- The "forward" and "inverse" transformations referred to are those defined when the MathMap is created (corresponding to the "fwd" and "inv" parameters of its constructor function). If the MathMap is inverted (i.e. its Invert attribute is non-zero), then the role of the SimpFI and SimpIF attributes will be interchanged.

Parameters:
simpIF - the SimpIF attribute of this object


Copyright © 2017 Central Laboratory of the Research Councils. All Rights Reserved.