|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectuk.ac.starlink.ast.AstObject
uk.ac.starlink.ast.Mapping
uk.ac.starlink.ast.MathMap
public class MathMap
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.
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
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 |
---|
public MathMap(int nin, int nout, String[] fwd, String[] inv)
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.
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.
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.
A
The following boolean operators are available:
The following relational operators are available:
Note that relational operators cannot usefully be used to compare
values with the
The following bitwise operators are available:
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").
All operators associate from left-to-right, except for unary +,
unary -, !, .not. and ** which associate from right-to-left.
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.
- 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
- 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.)
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.
- 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).
Symbolic Constants
The following symbolic constants are available (the enclosing "<>"
brackets must be included):
-
-
-
-
-
-
-
-
-
-
-
-
-
- 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.
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.
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").
AstException
- if an error occurred in the AST library
Method Detail |
---|
public int getSeed()
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.
public void setSeed(int seed)
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.
seed
- the Seed attribute of this objectpublic boolean getSimpFI()
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.
public void setSimpFI(boolean simpFI)
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.
simpFI
- the SimpFI attribute of this objectpublic boolean getSimpIF()
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.
public void setSimpIF(boolean simpIF)
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.
simpIF
- the SimpIF attribute of this object
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |