astPolyTran

Fit a PolyMap inverse or forward transformation

Description:

This function creates a new PolyMap which is a copy of the supplied PolyMap, in which a specified transformation (forward or inverse) has been replaced by a new polynomial transformation. The coefficients of the new transformation are estimated by sampling the other transformation and performing a least squares polynomial fit in the opposite direction to the sampled positions and values.

This method can only be used on (1-input,1-output) or (2-input,2-output) PolyMaps.

The transformation to create is specified by the " forward" parameter. In what follows " X" refers to the inputs of the PolyMap, and " Y" to the outputs of the PolyMap. The forward transformation transforms input values (X) into output values (Y), and the inverse transformation transforms output values (Y) into input values (X). Within a PolyMap, each transformation is represented by an independent set of polynomials, P_f or P_i: Y=P_f(X) for the forward transformation and X=P_i(Y) for the inverse transformation.

The " forward" parameter specifies the transformation to be replaced. If it is non-zero, a new forward transformation is created by first finding the input values (X) using the inverse transformation (which must be available) at a regular grid of points (Y) covering a rectangular region of the PolyMap s output space. The coefficients of the required forward polynomial, Y=P_f(X), are chosen in order to minimise the sum of the squared residuals between the sampled values of Y and P_f(X).

If " forward" is zero (probably the most likely case), a new inverse transformation is created by first finding the output values (Y) using the forward transformation (which must be available) at a regular grid of points (X) covering a rectangular region of the PolyMap s input space. The coefficients of the required inverse polynomial, X=P_i(Y), are chosen in order to minimise the sum of the squared residuals between the sampled values of X and P_i(Y).

This fitting process is performed repeatedly with increasing polynomial orders (starting with linear) until the target accuracy is achieved, or a specified maximum order is reached. If the target accuracy cannot be achieved even with this maximum-order polynomial, the best fitting maximum-order polynomial is returned so long as its accuracy is better than " maxacc" . If it is not, a NULL pointer is returned but no error is reported.

Synopsis

AstPolyMap astPolyTran( AstPolyMap this, int forward, double acc, double maxacc, int maxorder, const double lbnd, const double ubnd )

Parameters:

this
Pointer to the original Mapping.
forward
If non-zero, the forward PolyMap transformation is replaced. Otherwise the inverse transformation is replaced.
acc
The target accuracy, expressed as a geodesic distance within the PolyMap s input space (if " forward" is zero) or output space (if " forward" is non-zero).
maxacc
The maximum allowed accuracy for an acceptable polynomial, expressed as a geodesic distance within the PolyMap s input space (if " forward" is zero) or output space (if " forward" is non-zero).
maxorder
The maximum allowed polynomial order. This is one more than the maximum power of either input axis. So for instance, a value of 3 refers to a quadratic polynomial. Note, cross terms with total powers greater than or equal to maxorder are not inlcuded in the fit. So the maximum number of terms in each of the fitted polynomials is maxorder(maxorder+1)/2.
lbnd
Pointer to an array holding the lower bounds of a rectangular region within the PolyMap s input space (if " forward" is zero) or output space (if " forward" is non-zero). The new polynomial will be evaluated over this rectangle. The length of this array should equal the value of the PolyMap s Nin or Nout attribute, depending on " forward" .
ubnd
Pointer to an array holding the upper bounds of a rectangular region within the PolyMap s input space (if " forward" is zero) or output space (if " forward" is non-zero). The new polynomial will be evaluated over this rectangle. The length of this array should equal the value of the PolyMap s Nin or Nout attribute, depending on " forward" .

Applicability

PolyMap
All PolyMaps have this method.
ChebyMap
The ChebyMap implementation of this method allows NULL pointers to be supplied for " lbnd" and/or " ubnd" , in which case the corresponding bounds supplied when the ChebyMap was created are used. The returned PolyMap will be a ChebyMap, and the new transformation will be defined as a weighted sum of Chebyshev functions of the first kind.

Returned Value

astPolyTran()
A pointer to the new PolyMap. A NULL pointer will be returned if the fit fails to achieve the accuracy specified by " maxacc" , but no error will be reported.

Notes: