next up previous 264
Next: astRead - Read an Object from a Channel
Up: AST Function Descriptions
Previous: astRate - Calculate the rate of change of a Mapping output


astRateMap - Create a RateMap

Description:
This function creates a new RateMap and optionally initialises its attributes.

A RateMap is a Mapping which represents a single element of the Jacobian matrix of another Mapping. The Mapping for which the Jacobian is required is specified when the new RateMap is created, and is referred to as the "encapsulated Mapping" below.

The number of inputs to a RateMap is the same as the number of inputs to its encapsulated Mapping. The number of outputs from a RateMap is always one. This one output equals the rate of change of a specified output of the encapsulated Mapping with respect to a specified input of the encapsulated Mapping (the input and output to use are specified when the RateMap is created).

A RateMap which has not been inverted does not define an inverse transformation. If a RateMap has been inverted then it will define an inverse transformation but not a forward transformation.

Synopsis:
AstRateMap $*$astRateMap( AstMapping $*$map, int ax1, int ax2, const char $*$options, ... )
Parameters:
map
Pointer to the encapsulated Mapping.
ax1
Index of the output from the encapsulated Mapping for which the rate of change is required. This corresponds to the delta quantity forming the numerator of the required element of the Jacobian matrix. The first axis has index 1.
ax2
Index of the input to the encapsulated Mapping which is to be varied. This corresponds to the delta quantity forming the denominator of the required element of the Jacobian matrix. The first axis has index 1.
options
Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new RateMap. The syntax used is identical to that for the astSet function and may include "printf" format specifiers identified by "%" symbols in the normal way.
...
If the "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).
Returned Value:
astRateMap()
A pointer to the new RateMap.
Notes:
  • The forward transformation of the encapsulated Mapping must be defined.

  • Note that the component Mappings supplied are not copied by astRateMap (the new RateMap simply retains a reference to them). They may continue to be used for other purposes, but should not be deleted. If a RateMap containing a copy of its component Mappings is required, then a copy of the RateMap should be made using astCopy.

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


next up previous 264
Next: astRead - Read an Object from a Channel
Up: AST Function Descriptions
Previous: astRate - Calculate the rate of change of a Mapping output

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 211
R.F. Warren-Smith & D.S. Berry
24th May 2011
E-mail:ussc@star.rl.ac.uk

Copyright (C) 2009 Science \& Technology Facilities Council