UVES Pipeline Reference Manual  5.4.6
Data Structures | Functions
Polynomials

Data Structures

struct  _polynomial
 

Functions

polynomialuves_polynomial_new (const cpl_polynomial *pol)
 Create a polynomial. More...
 
polynomialuves_polynomial_new_zero (int dim)
 Create a zero polynomial. More...
 
void uves_polynomial_delete (polynomial **p)
 Delete a polynomial. More...
 
void uves_polynomial_delete_const (const polynomial **p)
 Delete a const polynomial. More...
 
int uves_polynomial_get_degree (const polynomial *p)
 Get degree. More...
 
polynomialuves_polynomial_duplicate (const polynomial *p)
 Copy a polynomial. More...
 
cpl_table * uves_polynomial_convert_to_table (const polynomial *p)
 Convert a polynomial to a table. More...
 
polynomialuves_polynomial_convert_from_table (cpl_table *t)
 Convert a table to a polynomial. More...
 
int uves_polynomial_get_dimension (const polynomial *p)
 Get the dimension of a polynomial. More...
 
void uves_polynomial_dump (const polynomial *p, FILE *stream)
 Print a polynomial. More...
 
cpl_error_code uves_polynomial_rescale (polynomial *p, int varno, double scale)
 Rescale a polynomial. More...
 
cpl_error_code uves_polynomial_shift (polynomial *p, int varno, double shift)
 Shift a polynomial. More...
 
double uves_polynomial_evaluate_1d (const polynomial *p, double x)
 Evaluate a 1d polynomial. More...
 
double uves_polynomial_evaluate_2d (const polynomial *p, double x1, double x2)
 Evaluate a 2d polynomial. More...
 
double uves_polynomial_solve_1d (const polynomial *p, double value, double guess, int multiplicity)
 Solve p(x) = value. More...
 
double uves_polynomial_solve_2d (const polynomial *p, double value, double guess, int multiplicity, int varno, double x_value)
 Solve p(x1, x2) = value. More...
 
double uves_polynomial_derivative_2d (const polynomial *p, double x1, double x2, int varno)
 Evaluate the partial derivative of a 2d polynomial. More...
 
double uves_polynomial_derivative_1d (const polynomial *p, double x)
 Evaluate the derivative of a 1d polynomial. More...
 
polynomialuves_polynomial_add_2d (const polynomial *p1, const polynomial *p2)
 Add two polynomials. More...
 
static cpl_error_code derivative_cpl_polynomial (cpl_polynomial *p, int varno)
 Calculate the partial derivative of a CPL-polynomial. More...
 
cpl_error_code uves_polynomial_derivative (polynomial *p, int varno)
 Calculate the partial derivative of a polynomial. More...
 
double uves_polynomial_get_coeff_2d (const polynomial *p, int degree1, int degree2)
 Get a coefficient of a 2D polynomial. More...
 
double uves_polynomial_get_coeff_1d (const polynomial *p, int degree)
 Get a coefficient of a 1D polynomial. More...
 
polynomialuves_polynomial_collapse (const polynomial *p, int varno, double value)
 Collapse a polynomial by fixing one variable to a constant. More...
 
polynomialuves_polynomial_fit_1d (const cpl_vector *x_pos, const cpl_vector *values, const cpl_vector *sigmas, int poly_deg, double *mse)
 Fit a 1d function with a polynomial. More...
 
polynomialuves_polynomial_fit_2d (const cpl_bivector *xy_pos, const cpl_vector *values, const cpl_vector *sigmas, int poly_deg1, int poly_deg2, double *mse, double *red_chisq, polynomial **variance)
 Fit a 2d surface with a polynomial in x and y. More...
 

Detailed Description

This module provides N dimensional polynomials.

This class is a wrapper of CPL's polynomial class, but it improves the accuracy of the fitting routine (related to DFS ticket: DFS02237), and it allows fitting with a 2d polynomial with different degree of the independent variables (which CPL does not support), and also allows propagation of the uncertainty of the fit.

Also, the module adds simple functionalities like shifting a 2d polynomial, collapsing a 2d polynomial to a 1d polynomial, and conversion of a polynomial to/from a CPL table (which can be used for I/O).

The functionality in this module has been implemented only as needed. Therefore, 1) some functionality which "should" to be there (like collapsing a polynomial of any dimension) is missing, but 2) all the functionality present has been tested.

Function Documentation

polynomial* uves_polynomial_new ( const cpl_polynomial *  pol)

Create a polynomial.

Parameters
polThe CPL polynomial to wrap
Returns
A new polynomial, which must be deallocated with uves_polynomial_delete(), or NULL on error.
Note
The provided CPL polynomial is duplicated and must still be deallocated independently from the polynomial returned from this function.

Definition at line 220 of file uves_utils_polynomial.c.

References assure_mem, check, _polynomial::pol, _polynomial::scale, _polynomial::shift, uves_polynomial_delete(), and _polynomial::vec.

Referenced by test_polynomial(), uves_polynomial_add_2d(), uves_polynomial_collapse(), uves_polynomial_convert_from_table(), uves_polynomial_duplicate(), uves_polynomial_fit_1d(), uves_polynomial_fit_2d(), and uves_polynomial_new_zero().

polynomial* uves_polynomial_new_zero ( int  dim)

Create a zero polynomial.

Parameters
dimDimension of polynomial
Returns
A new polynomial, which must be deallocated with uves_polynomial_delete(), or NULL on error.

Definition at line 267 of file uves_utils_polynomial.c.

References assure_mem, and uves_polynomial_new().

Referenced by opt_measure_profile(), opt_measure_profile_order(), and test_extract().

void uves_polynomial_delete ( polynomial **  p)
void uves_polynomial_delete_const ( const polynomial **  p)

Delete a const polynomial.

Parameters
ppolynomial to delete

p is deleted and set to NULL.

Definition at line 309 of file uves_utils_polynomial.c.

Referenced by uves_polynomial_delete(), and uves_reduce_scired().

int uves_polynomial_get_degree ( const polynomial p)

Get degree.

Parameters
ppolynomial
Returns
degree

Definition at line 328 of file uves_utils_polynomial.c.

References _polynomial::pol.

Referenced by opt_measure_profile(), and uves_polynomial_add_2d().

polynomial* uves_polynomial_duplicate ( const polynomial p)

Copy a polynomial.

Parameters
ppolynomial to copy
Returns
A clone of the input polynomial or NULL on error.

Definition at line 347 of file uves_utils_polynomial.c.

References check, _polynomial::pol, _polynomial::scale, _polynomial::shift, uves_polynomial_delete(), uves_polynomial_get_dimension(), and uves_polynomial_new().

Referenced by extract_ff_rebin_merge(), interpolate_wave(), repeat_orderdef(), uves_extract(), uves_polynomial_get_coeff_1d(), and uves_polynomial_get_coeff_2d().

cpl_table* uves_polynomial_convert_to_table ( const polynomial p)

Convert a polynomial to a table.

Parameters
ppolynomial to convert
Returns
A table representation of the polynomial, or NULL on error.

Currently, only 2d polynomials are supported. The polynomial is written to the table in an internal format ; Therefore the table should not be read or edited manually, but only read using the function uves_polynomial_convert_from_table() .

Definition at line 389 of file uves_utils_polynomial.c.

References _polynomial::pol, _polynomial::scale, _polynomial::shift, and uves_polynomial_get_dimension().

Referenced by extract_ff_rebin_merge().

polynomial* uves_polynomial_convert_from_table ( cpl_table *  t)

Convert a table to a polynomial.

Parameters
tTable to convert
Returns
The polynomial stored in the table, which must be deallocated with uves_polynomial_delete(), or NULL on error.

Currently, only 2d polynomials are supported. See also uves_polynomial_convert_to_table() .

Definition at line 473 of file uves_utils_polynomial.c.

References check, uves_msg_debug, uves_polynomial_delete(), uves_polynomial_new(), uves_polynomial_rescale(), uves_polynomial_shift(), and uves_tostring_cpl_type().

int uves_polynomial_get_dimension ( const polynomial p)
void uves_polynomial_dump ( const polynomial p,
FILE *  stream 
)

Print a polynomial.

Parameters
pThe polynomial to print
streamWhere to dump the polynomial (e.g. "stdout")

This function does not use CPL's messaging system and should be used only for debugging.

Definition at line 572 of file uves_utils_polynomial.c.

References _polynomial::pol, _polynomial::scale, _polynomial::shift, and uves_polynomial_get_dimension().

Referenced by opt_measure_profile_order().

cpl_error_code uves_polynomial_rescale ( polynomial p,
int  varno,
double  scale 
)

Rescale a polynomial.

Parameters
pThe polynomial to rescale
varnoRescale with respect to this variable (number)
scaleThe rescaling factor
Returns
CPL_ERROR_NONE iff OK

The variable specified by varno is rescaled: p (x_1, ..., x_varno, ..., x_n) :=p (x_1, ..., x_varno / scale, ..., x_n).

If varno is zero, a the polynomial itself is rescaled: p(x) := p(x) * scale . Negative values of varno are illegal.

Definition at line 605 of file uves_utils_polynomial.c.

References _polynomial::scale, _polynomial::shift, and uves_polynomial_get_dimension().

Referenced by interpolate_wave(), test_polynomial(), and uves_polynomial_convert_from_table().

cpl_error_code uves_polynomial_shift ( polynomial p,
int  varno,
double  shift 
)

Shift a polynomial.

Parameters
pThe polynomial to shift
varnoShift with respect to this variable (number)
shiftThe amount to shift
Returns
CPL_ERROR_NONE iff OK

The polynomial is shifted: p (x_1, ..., x_varno, ..., x_n) :=p (x_1, ..., x_varno - shift, ..., x_n).

If varno is zero, a constant is added to the polynomial: p(x) := p(x) + shift . Negative values of varno are illegal.

Definition at line 646 of file uves_utils_polynomial.c.

References _polynomial::shift, and uves_polynomial_get_dimension().

Referenced by opt_measure_profile(), opt_measure_profile_order(), test_extract(), uves_polynomial_convert_from_table(), uves_polynomial_fit_1d(), and uves_polynomial_fit_2d().

double uves_polynomial_evaluate_1d ( const polynomial p,
double  x 
)

Evaluate a 1d polynomial.

Parameters
pThe polynomial to evaluate
xWhere to evaluate the polynomial
Returns
p ( x ), or undefined on error.

The polynomial must be 1d. See also uves_polynomial_evaluate_2d() .

Definition at line 678 of file uves_utils_polynomial.c.

References check, _polynomial::pol, _polynomial::scale, _polynomial::shift, and uves_polynomial_get_dimension().

Referenced by opt_get_redchisq(), opt_measure_profile(), uves_get_blaze_ratio(), uves_polynomial_get_coeff_1d(), and uves_polynomial_regression_1d().

double uves_polynomial_evaluate_2d ( const polynomial p,
double  x1,
double  x2 
)
double uves_polynomial_solve_1d ( const polynomial p,
double  value,
double  guess,
int  multiplicity 
)

Solve p(x) = value.

Parameters
pThe input polynomial
valueThe requested value of the polynomial
guessA guess solution
multiplicityThe multiplycity of the root (or 1 if unknown)
Returns
x satisfying the equation p (x) = value, or undefined on error.

This function uses cpl_polynomial_solve_1d() to solve the equation p (x) = value . See cpl_polynomial_solve_1d() for a description of the algorithm.

Definition at line 747 of file uves_utils_polynomial.c.

References check, _polynomial::pol, _polynomial::scale, _polynomial::shift, and uves_polynomial_get_dimension().

Referenced by uves_polynomial_solve_2d(), uves_rebin(), and uves_response_efficiency().

double uves_polynomial_solve_2d ( const polynomial p,
double  value,
double  guess,
int  multiplicity,
int  varno,
double  x_value 
)

Solve p(x1, x2) = value.

Parameters
pThe input polynomial
valueThe requested value of the polynomial
guessA guess solution
multiplicityThe multiplycity of the root (or 1 if unknown)
varnoThe variable number to fix (1 or 2)
x_valueVariable number varno is fixed to this value
Returns
The solution of the equation, or undefined on error.

This function solves the equation p (x1, x2) = value, where either x1 or x2 is already fixed to x_value.

For example, to solve the equation p (37, x) = 500 for x, call uves_polynomial_solve_2d(p, 500, x_guess, 1, 1, 37) .

Definition at line 801 of file uves_utils_polynomial.c.

References check, uves_polynomial_collapse(), uves_polynomial_delete(), and uves_polynomial_solve_1d().

Referenced by opt_get_order_width(), and uves_draw_lines().

double uves_polynomial_derivative_2d ( const polynomial p,
double  x1,
double  x2,
int  varno 
)

Evaluate the partial derivative of a 2d polynomial.

Parameters
pThe input polynomial
x1Where to evaluate the derivative
x2Where to evaluate the derivative
varnoEvaluate partial derivative with respect to this variable (1 or 2)
Returns
dp/dx_varno evaluated at (x1, x2), or undefined on error.

Definition at line 832 of file uves_utils_polynomial.c.

References _polynomial::pol, _polynomial::scale, _polynomial::shift, and uves_polynomial_get_dimension().

Referenced by compute_lambda(), detect_ripples(), uves_rebin(), and uves_response_efficiency().

double uves_polynomial_derivative_1d ( const polynomial p,
double  x 
)

Evaluate the derivative of a 1d polynomial.

Parameters
pThe input polynomial
xWhere to evaluate the derivative
Returns
dp/dx evaluated at x, or undefined on error.

Definition at line 921 of file uves_utils_polynomial.c.

References check, _polynomial::pol, _polynomial::scale, _polynomial::shift, and uves_polynomial_get_dimension().

polynomial* uves_polynomial_add_2d ( const polynomial p1,
const polynomial p2 
)

Add two polynomials.

Parameters
p1left
p2right
Returns
p1 + p2

Definition at line 946 of file uves_utils_polynomial.c.

References uves_polynomial_get_coeff_2d(), uves_polynomial_get_degree(), uves_polynomial_get_dimension(), and uves_polynomial_new().

Referenced by interpolate_wave(), and test_polynomial().

static cpl_error_code derivative_cpl_polynomial ( cpl_polynomial *  p,
int  varno 
)
static

Calculate the partial derivative of a CPL-polynomial.

Parameters
pThe input polynomial
varnoDifferentiate with respect to this variable number (counting from 1 to dimension)
Returns
CPL_ERROR_NONE iff okay.

The polynomial is transformed from p to dp/dx_varno.

1D and 2D polynomials are supported.

Definition at line 1011 of file uves_utils_polynomial.c.

Referenced by uves_polynomial_derivative().

cpl_error_code uves_polynomial_derivative ( polynomial p,
int  varno 
)

Calculate the partial derivative of a polynomial.

Parameters
pThe input polynomial
varnoDifferentiate with respect to this variable number (counting from 1 to dimension)
Returns
CPL_ERROR_NONE iff okay.

The polynomial is transformed from p to dp/dx_varno.

Definition at line 1077 of file uves_utils_polynomial.c.

References check, derivative_cpl_polynomial(), _polynomial::pol, _polynomial::scale, _polynomial::shift, and uves_polynomial_get_dimension().

Referenced by uves_polynomial_get_coeff_1d(), and uves_polynomial_get_coeff_2d().

double uves_polynomial_get_coeff_2d ( const polynomial p,
int  degree1,
int  degree2 
)

Get a coefficient of a 2D polynomial.

Parameters
pThe input polynomial
degree1The coefficient degree
degree2The coefficient degree
Returns
The coefficient of the term (degree1, degree2), or undefined on error.

Definition at line 1120 of file uves_utils_polynomial.c.

References check, uves_polynomial_delete(), uves_polynomial_derivative(), uves_polynomial_duplicate(), uves_polynomial_evaluate_2d(), and uves_polynomial_get_dimension().

Referenced by test_polynomial(), test_polynomial_fit_2d(), uves_physmod_msrawxy(), uves_physmod_regress_echelle(), and uves_polynomial_add_2d().

double uves_polynomial_get_coeff_1d ( const polynomial p,
int  degree 
)

Get a coefficient of a 1D polynomial.

Parameters
pThe input polynomial
degreeCoefficient degree
Returns
The coefficient of the degree'th term, or undefined on error.

If the required degree is greater than the polynomial's degree, the function does not fail but returns 0 as it should.

Definition at line 1176 of file uves_utils_polynomial.c.

References check, uves_polynomial_delete(), uves_polynomial_derivative(), uves_polynomial_duplicate(), uves_polynomial_evaluate_1d(), and uves_polynomial_get_dimension().

Referenced by opt_measure_profile_order(), and uves_physmod_calmap().

polynomial* uves_polynomial_collapse ( const polynomial p,
int  varno,
double  value 
)

Collapse a polynomial by fixing one variable to a constant.

Parameters
pThe polynomial to collapse
varnoVariable number to fix
valueFix variable number varno to this value
Returns
A newly allocated, collapsed polynomial which must be deallocated with uves_polynomial_delete(), or NULL on error.

This function fixes one variable of a polynomial to a constant value, thereby producing a polynomial, p(x1, ..., x_varno = value, ..., xn), with dimension n - 1.

Currently, only n=2 is supported.

Definition at line 1231 of file uves_utils_polynomial.c.

References assure_mem, _polynomial::pol, _polynomial::scale, _polynomial::shift, uves_polynomial_delete(), uves_polynomial_get_dimension(), and uves_polynomial_new().

Referenced by uves_polynomial_solve_2d(), uves_rebin(), and uves_response_efficiency().

polynomial* uves_polynomial_fit_1d ( const cpl_vector *  x_pos,
const cpl_vector *  values,
const cpl_vector *  sigmas,
int  poly_deg,
double *  mse 
)

Fit a 1d function with a polynomial.

Parameters
x_posList of positions of the signal to fit.
valuesList of values of the signal to fit.
sigmasList of uncertainties of the surface points. If NULL, constant uncertainties are used.
poly_degPolynomial degree.
mseOutput mean squared error.
Returns
The fitted polynomial or NULL in error case

This function is a straightforward adaption of CPL's cpl_polynomial_fit_1d_create() . But before performing the fit, all values are shifted, so that they are centered around zero. This improves the accuracy of the fit.

Also, there's support for taking into account the uncertainties of the dependent variable.

See also cpl_polynomial_fit_1d_create() and uves_polynomial_regression_1d() .

Definition at line 1337 of file uves_utils_polynomial.c.

References assure_nomsg, check, uves_polynomial_new(), uves_polynomial_shift(), and uves_pow_int().

Referenced by uves_polynomial_regression_1d().

polynomial* uves_polynomial_fit_2d ( const cpl_bivector *  xy_pos,
const cpl_vector *  values,
const cpl_vector *  sigmas,
int  poly_deg1,
int  poly_deg2,
double *  mse,
double *  red_chisq,
polynomial **  variance 
)

Fit a 2d surface with a polynomial in x and y.

Parameters
xy_posList of positions of the surface to fit.
valuesList of values of the surface points.
sigmasList of uncertainties of the surface points.
poly_deg1Polynomial degree of 1st variable (x)
poly_deg2Polynomial degree of 2nd variable (y)
mseOutput mean squared error
red_chisqOutput reduced chi square
varianceVariance polynomial (see below)
Returns
The fitted polynomial or NULL in error case.

This function fits a 2d polynomial to a surface. The input grid is given in xy_pos and values. xy_pos and values of course must contain the same number of points. If sigmas is NULL, constant sigma (equal to 1) is used.

This function is an adaption of CPL's cpl_polynomial_fit_2d_create() . But the fit is made with a general rectangular coefficient matrix (the size of which is indicated by the polynomial degrees, poly_deg1 and poly_deg2) instead of the upper-left triangular matrix used by cpl_polynomial_fit_2d_create().

And before performing the fit, all values are shifted, so that they are centered around zero, which improves the accuracy of the fit. Rescaling with stdev makes the fit worse (empirically) so this is not done.

If mse is non-NULL, the mean squared error of the fit is returned through this variable. If red_chisq is non-NULL, the reduced chi square of the fit is returned through this variable.

If variance is non-NULL the variance polynomial defined as (using the error propagation formula for correlated coefficients {coeff_i}) variance(x,y) = sum_{ij} d(p_fit)/d(coeff_i) * cov_{ij} * d(p_fit)/d(coeff_j) = sum_{ij} x^degx[i]*y^degy[i] * cov_{ij} * x^degx[j]*y^degy[j] = sum_{ij} cov_{ij} * x^(degx[i]+degx[j]) * y^(degy[i]+degy[j]) will be returned through this variable (i.e. the parameter must be the address of a (polynomial*) variable. The variance polynomial gives the associated uncertainty when evaluating the fitted polynomial, i.e. the variance of p_fit(x, y) = sum_{ij} (a_{ij} * x^i * y^j)

See also cpl_polynomial_fit_2d_create() and uves_polynomial_regression_2d() .

Definition at line 1517 of file uves_utils_polynomial.c.

References assure_mem, passure, uves_polynomial_evaluate_2d(), uves_polynomial_new(), uves_polynomial_shift(), and uves_pow_int().

Referenced by test_polynomial_fit_2d(), and uves_polynomial_regression_2d().