#### Description:

This attribute indicates whether the original inverse transformation of the PolyMap should be implemented via an iterative Newton-Raphson approximation that uses the forward transformation to transform candidate input positions until an output position is found which is close to the required output position. By default, an iterative inverse is provided if, and only if, no inverse polynomial was supplied when the PolyMap was constructed.

Note, the term `"` inverse transformation`"` here refers to the inverse transformation of the original PolyMap, ignoring any subsequent inversions. Also, `"` input`"` and `"` output`"` refer to the inputs and outputs of the original PolyMap.

The NiterInverse and TolInverse attributes provide parameters that control the behaviour of the inverse approximation method.

The iterative inverse returns AST__BAD axis values at positions for which the inverse transformation is undefined. For instance, if the forward transformation is y = x∗x, the iterative inverse will return x = AST__BAD at y = -1. If the inverse transformation is multiply defined, the position returned by the iterative inverse will be the position of the solution that is closest to the supplied position. For instance, using the above example, y = x∗x, the iterative inverse will return x = +2 at y = 4, because x = +2 is the closest solution to 4 (the other solution is x = -2).

Type:

  Integer (boolean).

#### Applicability

##### PolyMap

All PolyMaps have this attribute.

##### ChebyMap

The ChebyMap class does not currently provide an option for an iterative inverse, and so the IterInverse value is always zero. Setting or clearing the IterInverse attribute of a ChebyMap has no effect.

#### Notes:

- The transformation replaced by the iterative algorithm is the transformation from the original PolyMap output space to the original PolyMap input space (i.e. the input and output spaces as defined by the arguments of the PolyMap constructor). This is still the case even if the PolyMap has subsequently been inverted. In other words if a PolyMap is created and then inverted, setting the IterInverse to a non-zero value will replace the forward transformation of the inverted PolyMap (i.e. the inverse transformation of the original PolyMap). It is not possible to replace the other transformation (i.e. from the original PolyMap input space to the original PolyMap output space) with an iterative algorithm.

- If a PolyMap that has an iterative inverse transformation is subsequently inverted, the inverted PolyMap will have an iterative forward transformation.

- An iterative inverse can only be used if the PolyMap has equal numbers of inputs and outputs, as given by the Nin and Nout attributes. An error will be reported if IterInverse is set non-zero for a PolyMap that does not meet this requirement.

Copyright (C) 2021 East Asian Observatory