#### Description:

This function creates a new ChebyMap and optionally initialises its attributes.

A ChebyMap is a form of Mapping which performs a Chebyshev polynomial transformation. Each output coordinate is a linear combination of Chebyshev polynomials of the first kind, of order zero up to a specified maximum order, evaluated at the input coordinates. The coefficients to be used in the linear combination are specified separately for each output coordinate.

For a 1-dimensional ChebyMap, the forward transformation is defined as follows:

f(x) = c0.T0(x`’` ) + c1.T1(x`’` ) + c2.T2(x`’` ) + ...

where:

- Tn(x`’` ) is the nth Chebyshev polynomial of the first kind:

- T0(x`’` ) = 1

- T1(x`’` ) = x`’`

- Tn+1(x`’` ) = 2.x`’` .Tn(x`’` ) + Tn-1(x`’` )

- x`’` is the inpux axis value, x, offset and scaled to the range [-1, 1] as x ranges over a specified bounding box, given when the ChebyMap is created. The input positions, x, supplied to the forward transformation must fall within the bounding box - bad axis values (AST__BAD) are generated for points outside the bounding box.

For an N-dimensional ChebyMap, the forward transformation is a generalisation of the above form. Each output axis value is the sum of `"` ncoeff`"` terms, where each term is the product of a single coefficient value and N factors of the form Tn(x`’` _i), where `"` x`’` _i`"` is the normalised value of the i`’` th input axis value.

The forward and inverse transformations are defined independantly by separate sets of coefficients, supplied when the ChebyMap is created. If no coefficients are supplied to define the inverse transformation, the astPolyTran method of the parent PolyMap class can instead be used to create an inverse transformation. The inverse transformation so generated will be a Chebyshev polynomial with coefficients chosen to minimise the residuals left by a round trip (forward transformation followed by inverse transformation).

#### Synopsis

AstChebyMap ∗astChebyMap( int nin, int nout, int ncoeff_f, const double coeff_f[], int ncoeff_i, const double coeff_i[], const double lbnd_f[], const double ubnd_f[], const double lbnd_i[], const double ubnd_i[], const char ∗options, ... )

#### Parameters:

##### nin

The number of input coordinates.

##### nout

The number of output coordinates.

##### ncoeff_f

The number of non-zero coefficients necessary to define the forward transformation of the ChebyMap. If zero is supplied, the forward transformation will be undefined.

##### coeff_f

An array containing `"` ncoeff_f∗( 2 + nin )`"` elements. Each group of `"` 2 + nin`"` adjacent elements describe a single coefficient of the forward transformation. Within each such group, the first element is the coefficient value; the next element is the integer index of the ChebyMap output which uses the coefficient within its defining expression (the first output has index 1); the remaining elements of the group give the integer powers to use with each input coordinate value (powers must not be negative, and floating point values are rounded to the nearest integer). If `"` ncoeff_f`"` is zero, a NULL pointer may be supplied for `"` coeff_f`"` .

For instance, if the ChebyMap has 3 inputs and 2 outputs, each group consisting of 5 elements, A groups such as `"` (1.2, 2.0, 1.0, 3.0, 0.0)`"` describes a coefficient with value 1.2 which is used within the definition of output 2. The output value is incremented by the product of the coefficient value, the value of the Chebyshev polynomial of power 1 evaluated at input coordinate 1, and the value of the Chebyshev polynomial of power 3 evaluated at input coordinate 2. Input coordinate 3 is not used since its power is specified as zero. As another example, the group `"` (-1.0, 1.0, 0.0, 0.0, 0.0 )`"` adds a constant value -1.0 onto output 1 (it is a constant value since the power for every input axis is given as zero).

Each final output coordinate value is the sum of the `"` ncoeff_f`"` terms described by the `"` ncoeff_f`"` groups within the supplied array.

##### ncoeff_i

The number of non-zero coefficients necessary to define the inverse transformation of the ChebyMap. If zero is supplied, the inverse transformation will be undefined.

##### coeff_i

An array containing `"` ncoeff_i∗( 2 + nout )`"` elements. Each group of `"` 2 + nout`"` adjacent elements describe a single coefficient of the inverse transformation, using the same schame as `"` coeff_f`"` , except that `"` inputs`"` and `"` outputs`"` are transposed. If `"` ncoeff_i`"` is zero, a NULL pointer may be supplied for `"` coeff_i`"` .

##### lbnd_f

An array containing the lower bounds of the input bounding box within which the ChebyMap is defined. This argument is not used or accessed if ncoeff_f is zero, and so a NULL pointer may be supplied. If supplied, the array should contain `"` nin`"` elements.

##### ubnd_f

An array containing the upper bounds of the input bounding box within which the ChebyMap is defined. This argument is not used or accessed if ncoeff_f is zero, and so a NULL pointer may be supplied. If supplied, the array should contain `"` nin`"` elements.

##### lbnd_i

An array containing the lower bounds of the output bounding box within which the ChebyMap is defined. This argument is not used or accessed if ncoeff_i is zero, and so a NULL pointer may be supplied. If supplied, the array should contain `"` nout`"` elements.

##### ubnd_i

An array containing the upper bounds of the output bounding box within which the ChebyMap is defined. This argument is not used or accessed if ncoeff_i is zero, and so a NULL pointer may be supplied. If supplied, the array should contain `"` nout`"` elements.

##### options

Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new ChebyMap. 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

##### astChebyMap()

A pointer to the new ChebyMap.

#### Notes:

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

Copyright (C) 2021 East Asian Observatory