X-shooter Pipeline Reference Manual 3.8.15
Data Structures | Functions
Polynomials

Data Structures

struct  _polynomial
 

Functions

cpl_matrix * xsh_matrix_product_normal_create (const cpl_matrix *self)
 
cpl_matrix * xsh_matrix_solve_normal (const cpl_matrix *coeff, const cpl_matrix *rhs)
 
polynomialxsh_polynomial_new (const cpl_polynomial *pol)
 Create a polynomial.
 
polynomialxsh_polynomial_new_zero (int dim)
 Create a zero polynomial.
 
void xsh_polynomial_delete (polynomial **p)
 Delete a polynomial.
 
void xsh_polynomial_delete_const (const polynomial **p)
 Delete a const polynomial.
 
int xsh_polynomial_get_degree (const polynomial *p)
 Get degree.
 
polynomialxsh_polynomial_duplicate (const polynomial *p)
 Copy a polynomial.
 
cpl_table * xsh_polynomial_convert_to_table (const polynomial *p)
 Convert a polynomial to a table.
 
polynomialxsh_polynomial_convert_from_table (cpl_table *t)
 Convert a table to a polynomial.
 
int xsh_polynomial_get_dimension (const polynomial *p)
 Get the dimension of a polynomial.
 
void xsh_polynomial_dump (const polynomial *p, FILE *stream)
 Print a polynomial.
 
cpl_error_code xsh_polynomial_rescale (polynomial *p, int varno, double scale)
 Rescale a polynomial.
 
cpl_error_code xsh_polynomial_shift (polynomial *p, int varno, double shift)
 Shift a polynomial.
 
double xsh_polynomial_evaluate_1d (const polynomial *p, double x)
 Evaluate a 1d polynomial.
 
double xsh_polynomial_evaluate_2d (const polynomial *p, double x1, double x2)
 Evaluate a 2d polynomial.
 
double xsh_polynomial_solve_1d (const polynomial *p, double value, double guess, int multiplicity)
 Solve p(x) = value.
 
double xsh_polynomial_solve_2d (const polynomial *p, double value, double guess, int multiplicity, int varno, double x_value)
 Solve p(x1, x2) = value.
 
double xsh_polynomial_derivative_2d (const polynomial *p, double x1, double x2, int varno)
 Evaluate the partial derivative of a 2d polynomial.
 
double xsh_polynomial_derivative_1d (const polynomial *p, double x)
 Evaluate the derivative of a 1d polynomial.
 
polynomialxsh_polynomial_add_2d (const polynomial *p1, const polynomial *p2)
 Add two polynomials.
 
static cpl_error_code derivative_cpl_polynomial (cpl_polynomial *p, int varno)
 Calculate the partial derivative of a CPL-polynomial.
 
cpl_error_code xsh_polynomial_derivative (polynomial *p, int varno)
 Calculate the partial derivative of a polynomial.
 
double xsh_polynomial_get_coeff_2d (const polynomial *p, int degree1, int degree2)
 Get a coefficient of a 2D polynomial.
 
double xsh_polynomial_get_coeff_1d (const polynomial *p, int degree)
 Get a coefficient of a 1D polynomial.
 
polynomialxsh_polynomial_collapse (const polynomial *p, int varno, double value)
 Collapse a polynomial by fixing one variable to a constant.
 
polynomialxsh_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.
 
polynomialxsh_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.
 

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

◆ derivative_cpl_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 993 of file xsh_utils_polynomial.c.

References assure, degree, and dimension.

Referenced by xsh_polynomial_derivative().

◆ xsh_matrix_product_normal_create()

cpl_matrix * xsh_matrix_product_normal_create ( const cpl_matrix *  self)

Definition at line 106 of file xsh_utils_polynomial.c.

References m, and n.

Referenced by xsh_matrix_solve_normal().

◆ xsh_matrix_solve_normal()

cpl_matrix * xsh_matrix_solve_normal ( const cpl_matrix *  coeff,
const cpl_matrix *  rhs 
)

◆ xsh_polynomial_add_2d()

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

Add two polynomials.

Parameters
p1left
p2right
Returns
p1 + p2

Definition at line 928 of file xsh_utils_polynomial.c.

References assure, degree, xsh_free_polynomial(), xsh_max_int(), xsh_polynomial_get_coeff_2d(), xsh_polynomial_get_degree(), xsh_polynomial_get_dimension(), and xsh_polynomial_new().

◆ xsh_polynomial_collapse()

polynomial * xsh_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 xsh_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 1213 of file xsh_utils_polynomial.c.

References assure, assure_mem, degree, dimension, _polynomial::pol, _polynomial::scale, _polynomial::shift, xsh_free_polynomial(), xsh_polynomial_delete(), xsh_polynomial_get_dimension(), and xsh_polynomial_new().

Referenced by xsh_polynomial_solve_2d().

◆ xsh_polynomial_convert_from_table()

polynomial * xsh_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 xsh_polynomial_delete(), or NULL on error.

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

Definition at line 456 of file xsh_utils_polynomial.c.

References assure, check_msg, COLUMN_COEFF, COLUMN_ORDER1, COLUMN_ORDER2, xsh_free_polynomial(), xsh_msg_debug, xsh_polynomial_delete(), xsh_polynomial_new(), xsh_polynomial_rescale(), xsh_polynomial_shift(), and xsh_tostring_cpl_type().

◆ xsh_polynomial_convert_to_table()

cpl_table * xsh_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 xsh_polynomial_convert_from_table() .

Definition at line 376 of file xsh_utils_polynomial.c.

References assure, COLUMN_COEFF, COLUMN_ORDER1, COLUMN_ORDER2, degree, _polynomial::pol, _polynomial::scale, _polynomial::shift, and xsh_polynomial_get_dimension().

◆ xsh_polynomial_delete()

void xsh_polynomial_delete ( polynomial **  p)

◆ xsh_polynomial_delete_const()

void xsh_polynomial_delete_const ( const polynomial **  p)

Delete a const polynomial.

Parameters
ppolynomial to delete

p is deleted and set to NULL.

Definition at line 296 of file xsh_utils_polynomial.c.

References xsh_free().

Referenced by xsh_polynomial_delete().

◆ xsh_polynomial_derivative()

cpl_error_code xsh_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 1059 of file xsh_utils_polynomial.c.

References assure, check_msg, derivative_cpl_polynomial(), dimension, _polynomial::pol, _polynomial::scale, _polynomial::shift, and xsh_polynomial_get_dimension().

Referenced by xsh_polynomial_get_coeff_1d(), and xsh_polynomial_get_coeff_2d().

◆ xsh_polynomial_derivative_1d()

double xsh_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 904 of file xsh_utils_polynomial.c.

References assure, check_msg, _polynomial::pol, _polynomial::scale, _polynomial::shift, x, and xsh_polynomial_get_dimension().

◆ xsh_polynomial_derivative_2d()

double xsh_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 815 of file xsh_utils_polynomial.c.

References assure, degree, _polynomial::pol, _polynomial::scale, _polynomial::shift, and xsh_polynomial_get_dimension().

◆ xsh_polynomial_dump()

void xsh_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 555 of file xsh_utils_polynomial.c.

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

◆ xsh_polynomial_duplicate()

polynomial * xsh_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 334 of file xsh_utils_polynomial.c.

References assure, check_msg, dimension, _polynomial::pol, _polynomial::scale, _polynomial::shift, xsh_polynomial_delete(), xsh_polynomial_get_dimension(), and xsh_polynomial_new().

Referenced by xsh_polynomial_get_coeff_1d(), and xsh_polynomial_get_coeff_2d().

◆ xsh_polynomial_evaluate_1d()

double xsh_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 xsh_polynomial_evaluate_2d() .

Definition at line 661 of file xsh_utils_polynomial.c.

References assure, check_msg, _polynomial::pol, _polynomial::scale, _polynomial::shift, x, and xsh_polynomial_get_dimension().

Referenced by xsh_polynomial_get_coeff_1d().

◆ xsh_polynomial_evaluate_2d()

double xsh_polynomial_evaluate_2d ( const polynomial p,
double  x1,
double  x2 
)

Evaluate a 2d polynomial.

Parameters
pThe polynomial to evaluate
x1Where to evaluate the polynomial
x2Where to evaluate the polynomial
Returns
p ( x1 ,x2 ), or undefined on error.

The polynomial must be 2d. See also xsh_polynomial_evaluate_1d() .

Definition at line 692 of file xsh_utils_polynomial.c.

References assure, _polynomial::dimension, _polynomial::pol, _polynomial::scale, _polynomial::shift, _polynomial::vec, and _polynomial::vec_data.

Referenced by xsh_image_generate_background(), xsh_polynomial_fit_2d(), xsh_polynomial_get_coeff_2d(), and xsh_polynomial_regression_2d().

◆ xsh_polynomial_fit_1d()

polynomial * xsh_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 xsh_polynomial_regression_1d() .

Definition at line 1319 of file xsh_utils_polynomial.c.

References assure, assure_nomsg, check_msg, xsh_free_matrix(), xsh_free_polynomial(), xsh_free_vector(), xsh_matrix_solve_normal(), xsh_polynomial_new(), xsh_polynomial_shift(), and xsh_pow_int().

◆ xsh_polynomial_fit_2d()

polynomial * xsh_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 xsh_polynomial_regression_2d() .

Definition at line 1499 of file xsh_utils_polynomial.c.

References assure, assure_mem, passure, xsh_free_matrix(), xsh_free_polynomial(), xsh_matrix_solve_normal(), xsh_polynomial_evaluate_2d(), xsh_polynomial_new(), and xsh_polynomial_shift().

Referenced by xsh_polynomial_regression_2d().

◆ xsh_polynomial_get_coeff_1d()

double xsh_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 1158 of file xsh_utils_polynomial.c.

References assure, check_msg, degree, dimension, xsh_polynomial_delete(), xsh_polynomial_derivative(), xsh_polynomial_duplicate(), xsh_polynomial_evaluate_1d(), and xsh_polynomial_get_dimension().

◆ xsh_polynomial_get_coeff_2d()

double xsh_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 1102 of file xsh_utils_polynomial.c.

References assure, check_msg, dimension, xsh_polynomial_delete(), xsh_polynomial_derivative(), xsh_polynomial_duplicate(), xsh_polynomial_evaluate_2d(), and xsh_polynomial_get_dimension().

Referenced by xsh_polynomial_add_2d().

◆ xsh_polynomial_get_degree()

int xsh_polynomial_get_degree ( const polynomial p)

Get degree.

Parameters
ppolynomial
Returns
degree

Definition at line 315 of file xsh_utils_polynomial.c.

References assure, and _polynomial::pol.

Referenced by xsh_polynomial_add_2d().

◆ xsh_polynomial_get_dimension()

int xsh_polynomial_get_dimension ( const polynomial p)

◆ xsh_polynomial_new()

polynomial * xsh_polynomial_new ( const cpl_polynomial *  pol)

Create a polynomial.

Parameters
polThe CPL polynomial to wrap
Returns
A new polynomial, which must be deallocated with xsh_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 207 of file xsh_utils_polynomial.c.

References assure, assure_mem, check_msg, _polynomial::dimension, _polynomial::pol, _polynomial::scale, _polynomial::shift, _polynomial::vec, _polynomial::vec_data, and xsh_polynomial_delete().

Referenced by xsh_polynomial_add_2d(), xsh_polynomial_collapse(), xsh_polynomial_convert_from_table(), xsh_polynomial_duplicate(), xsh_polynomial_fit_1d(), xsh_polynomial_fit_2d(), and xsh_polynomial_new_zero().

◆ xsh_polynomial_new_zero()

polynomial * xsh_polynomial_new_zero ( int  dim)

Create a zero polynomial.

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

Definition at line 254 of file xsh_utils_polynomial.c.

References assure, assure_mem, xsh_free_polynomial(), and xsh_polynomial_new().

◆ xsh_polynomial_rescale()

cpl_error_code xsh_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 588 of file xsh_utils_polynomial.c.

References assure, _polynomial::scale, _polynomial::shift, and xsh_polynomial_get_dimension().

Referenced by xsh_polynomial_convert_from_table().

◆ xsh_polynomial_shift()

cpl_error_code xsh_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 629 of file xsh_utils_polynomial.c.

References assure, _polynomial::shift, and xsh_polynomial_get_dimension().

Referenced by xsh_polynomial_convert_from_table(), xsh_polynomial_fit_1d(), and xsh_polynomial_fit_2d().

◆ xsh_polynomial_solve_1d()

double xsh_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 730 of file xsh_utils_polynomial.c.

References assure, check_msg, _polynomial::pol, _polynomial::scale, _polynomial::shift, and xsh_polynomial_get_dimension().

Referenced by xsh_polynomial_solve_2d().

◆ xsh_polynomial_solve_2d()

double xsh_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 xsh_polynomial_solve_2d(p, 500, x_guess, 1, 1, 37) .

Definition at line 784 of file xsh_utils_polynomial.c.

References assure, check_msg, xsh_polynomial_collapse(), xsh_polynomial_delete(), and xsh_polynomial_solve_1d().