Create a MathMap
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.
"
nout"
,
but may be increased to accommodate any additional expressions which define
intermediate variables for the forward transformation (see the "
Calculating
Intermediate Values"
section below). "
nfwd"
elements) of
pointers to null terminated strings which contain the expressions defining the
forward transformation. The syntax of these expressions is described below. "
nin"
, but may be increased to accommodate any
additional expressions which define intermediate variables for the inverse
transformation (see the "
Calculating Intermediate Values"
section below). "
ninv"
elements) of pointers to null terminated strings which
contain the expressions defining the inverse transformation. The syntax of these
expressions is described below. "
printf"
format specifiers identified by "
%"
symbols in
the normal way. If no initialisation is required, a zero-length string may be
supplied. "
options"
string contains "
%"
format specifiers,
then an optional list of additional arguments may follow it in order to supply
values to be substituted for these specifiers. The rules for supplying these are
identical to those for the astSet function (and for the C "
printf"
function). 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.
’
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 $\ast $
x $+$ y
$\ast $ 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 $\ast $
cos( theta )"
"
y = r $\ast $
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.
"
r = sqrt( xin $\ast $
xin $+$
yin $\ast $
yin )"
"
rout = r $\ast $
( 1 $+$
0.1 $\ast $ r
$\ast $ r
)"
"
theta = atan2( yin, xin )"
"
xout = rout $\ast $
cos( theta )"
"
yout = rout $\ast $
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.
"
_"
. There is no built-in limit to the length of variable names. "
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. "
$<$bad$>$"
.
A $<$bad$>$ 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.
x1 $+$
x2: Sum of "
x1"
and "
x2"
.
x1 - x2: Difference of "
x1"
and "
x2"
.
x1 $\ast $
x2: Product of "
x1"
and "
x1"
.
x1 / x2: Ratio of "
x1"
and "
x2"
.
x1 $\ast $$\ast $
x2: "
x1"
raised to the power of "
x2"
.
$+$ x: Unary plus, has no effect on its argument.
- x: Unary minus, negates its argument.
"
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.)
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 $<$bad$>$ value (representing missing data), because the result is always $<$bad$>$. The isbad() function should be used instead.
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 ("
$\sim $"
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"
).
abs(x): Absolute value of "
x"
(sign removal), same as fabs(x).
acos(x): Inverse cosine of "
x"
, in radians.
acosd(x): Inverse cosine of "
x"
, in degrees.
acosh(x): Inverse hyperbolic cosine of "
x"
.
acoth(x): Inverse hyperbolic cotangent of "
x"
.
acsch(x): Inverse hyperbolic cosecant of "
x"
.
aint(x): Integer part of "
x"
(round towards zero), same as int(x).
asech(x): Inverse hyperbolic secant of "
x"
.
asin(x): Inverse sine of "
x"
, in radians.
asind(x): Inverse sine of "
x"
, in degrees.
asinh(x): Inverse hyperbolic sine of "
x"
.
atan(x): Inverse tangent of "
x"
, in radians.
atand(x): Inverse tangent of "
x"
, in degrees.
atanh(x): Inverse hyperbolic tangent of "
x"
.
atan2(x1, x2): Inverse tangent of "
x1/x2"
, in radians.
atan2d(x1, x2): Inverse tangent of "
x1/x2"
, in degrees.
ceil(x): Smallest integer value not less then "
x"
(round towards plus infinity).
cos(x): Cosine of "
x"
in radians.
cosd(x): Cosine of "
x"
in degrees.
cosh(x): Hyperbolic cosine of "
x"
.
coth(x): Hyperbolic cotangent of "
x"
.
csch(x): Hyperbolic cosecant of "
x"
.
dim(x1, x2): Returns "
x1-x2"
if "
x1"
is greater than "
x2"
, otherwise 0.
exp(x): Exponential function of "
x"
.
fabs(x): Absolute value of "
x"
(sign removal), same as abs(x).
floor(x): Largest integer not greater than "
x"
(round towards minus infinity).
fmod(x1, x2): Remainder when "
x1"
is divided by "
x2"
, same as mod(x1, x2).
gauss(x1, x2): Random sample from a Gaussian distribution with mean "
x1"
and standard
deviation "
x2"
.
int(x): Integer part of "
x"
(round towards zero), same as aint(x).
isbad(x): Returns 1 if "
x"
has the
$<$bad$>$
value (AST__BAD), otherwise 0.
log(x): Natural logarithm of "
x"
.
log10(x): Logarithm of "
x"
to base 10.
max(x1, x2, ...): Maximum of two or more values.
min(x1, x2, ...): Minimum of two or more values.
mod(x1, x2): Remainder when "
x1"
is divided by "
x2"
, same as fmod(x1, x2).
nint(x): Nearest integer to "
x"
(round to nearest).
poisson(x): Random integer-valued sample from a Poisson distribution with mean "
x"
.
pow(x1, x2): "
x1"
raised to the power of "
x2"
.
qif(x1, x2, x3): Returns "
x2"
if "
x1"
is true, and "
x3"
otherwise.
rand(x1, x2): Random sample from a uniform distribution in the range "
x1"
to "
x2"
inclusive.
sech(x): Hyperbolic secant of "
x"
.
sign(x1, x2): Absolute value of "
x1"
with the sign of "
x2"
(transfer of sign).
sin(x): Sine of "
x"
in radians.
sinc(x): Sinc function of "
x"
[= "
sin(x)/x"
].
sind(x): Sine of "
x"
in degrees.
sinh(x): Hyperbolic sine of "
x"
.
sqr(x): Square of "
x"
(= "
x$\ast $x"
).
sqrt(x): Square root of "
x"
.
tan(x): Tangent of "
x"
in radians.
tand(x): Tangent of "
x"
in degrees.
tanh(x): Hyperbolic tangent of "
x"
.
"
$<$$>$"
brackets must be included): $<$bad$>$:
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
$<$bad$>$.
The isbad() function should be used instead.
$<$dig$>$: Number of decimal digits of precision available in a floating point (double) value.
$<$e$>$: Base of natural logarithms.
$<$epsilon$>$: Smallest positive number such that 1.0$+$$<$epsilon$>$ is distinguishable from unity.
$<$mant_dig$>$: The number of base $<$radix$>$ digits stored in the mantissa of a floating point (double) value.
$<$max$>$: Maximum representable floating point (double) value.
$<$max_10_exp$>$: Maximum integer such that 10 raised to that power can be represented as a floating point (double) value.
$<$max_exp$>$: Maximum integer such that $<$radix$>$ raised to that power minus 1 can be represented as a floating point (double) value.
$<$min$>$: Smallest positive number which can be represented as a normalised floating point (double) value.
$<$min_10_exp$>$: Minimum negative integer such that 10 raised to that power can be represented as a normalised floating point (double) value.
$<$min_exp$>$: Minimum negative integer such that $<$radix$>$ raised to that power minus 1 can be represented as a normalised floating point (double) value.
$<$pi$>$: Ratio of the circumference of a circle to its diameter.
$<$radix$>$: The radix (number base) used to represent the mantissa of floating point (double) values.
$<$rounds$>$: 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.
Constants and variables
Function arguments and parenthesised expressions
Function invocations
Unary $+$ - ! .not.
$\ast $$\ast $
$\ast $ /
$+$ -
$<$$<$ $>$$>$
$<$ .lt. $<$= .le. $>$ .gt. $>$= .ge.
== .eq. != .ne.
&
$$
$|$
&& .and.
$$
$$
$|$$|$ .or
.eqv. .neqv. .xor.
All operators associate from left-to-right, except for unary $+$, unary -, !, .not. and $\ast $$\ast $ which associate from right-to-left.