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

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

Calculate the partial derivative of a CPL-polynomial.

Parameters:
p The input polynomial
varno Differentiate 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 994 of file xsh_utils_polynomial.c.

References assure, degree, and dimension.

Referenced by xsh_polynomial_derivative().

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

cpl_matrix* xsh_matrix_solve_normal ( const cpl_matrix *  coeff,
const cpl_matrix *  rhs 
)
polynomial* xsh_polynomial_add_2d ( const polynomial p1,
const polynomial p2 
)

Add two polynomials.

Parameters:
p1 left
p2 right
Returns:
p1 + p2

Definition at line 929 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().

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

Collapse a polynomial by fixing one variable to a constant.

Parameters:
p The polynomial to collapse
varno Variable number to fix
value Fix 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 1214 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().

polynomial* xsh_polynomial_convert_from_table ( cpl_table *  t  ) 

Convert a table to a polynomial.

Parameters:
t Table 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().

cpl_table* xsh_polynomial_convert_to_table ( const polynomial p  ) 

Convert a polynomial to a table.

Parameters:
p polynomial 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().

void xsh_polynomial_delete ( polynomial **  p  ) 
void xsh_polynomial_delete_const ( const polynomial **  p  ) 

Delete a const polynomial.

Parameters:
p polynomial 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().

cpl_error_code xsh_polynomial_derivative ( polynomial p,
int  varno 
)

Calculate the partial derivative of a polynomial.

Parameters:
p The input polynomial
varno Differentiate 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 1060 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().

double xsh_polynomial_derivative_1d ( const polynomial p,
double  x 
)

Evaluate the derivative of a 1d polynomial.

Parameters:
p The input polynomial
x Where 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, and xsh_polynomial_get_dimension().

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

Evaluate the partial derivative of a 2d polynomial.

Parameters:
p The input polynomial
x1 Where to evaluate the derivative
x2 Where to evaluate the derivative
varno Evaluate 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().

void xsh_polynomial_dump ( const polynomial p,
FILE *  stream 
)

Print a polynomial.

Parameters:
p The polynomial to print
stream Where 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().

polynomial* xsh_polynomial_duplicate ( const polynomial p  ) 

Copy a polynomial.

Parameters:
p polynomial 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().

double xsh_polynomial_evaluate_1d ( const polynomial p,
double  x 
)

Evaluate a 1d polynomial.

Parameters:
p The polynomial to evaluate
x Where 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, and xsh_polynomial_get_dimension().

Referenced by xsh_polynomial_get_coeff_1d().

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

Evaluate a 2d polynomial.

Parameters:
p The polynomial to evaluate
x1 Where to evaluate the polynomial
x2 Where 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().

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_pos List of positions of the signal to fit.
values List of values of the signal to fit.
sigmas List of uncertainties of the surface points. If NULL, constant uncertainties are used.
poly_deg Polynomial degree.
mse Output 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 1320 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().

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_pos List of positions of the surface to fit.
values List of values of the surface points.
sigmas List of uncertainties of the surface points.
poly_deg1 Polynomial degree of 1st variable (x)
poly_deg2 Polynomial degree of 2nd variable (y)
mse Output mean squared error
red_chisq Output reduced chi square
variance Variance 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 1500 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().

double xsh_polynomial_get_coeff_1d ( const polynomial p,
int  degree 
)

Get a coefficient of a 1D polynomial.

Parameters:
p The input polynomial
degree Coefficient 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 1159 of file xsh_utils_polynomial.c.

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

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

Get a coefficient of a 2D polynomial.

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

Definition at line 1103 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().

int xsh_polynomial_get_degree ( const polynomial p  ) 

Get degree.

Parameters:
p polynomial
Returns:
degree

Definition at line 315 of file xsh_utils_polynomial.c.

References assure, and _polynomial::pol.

Referenced by xsh_polynomial_add_2d().

int xsh_polynomial_get_dimension ( const polynomial p  ) 
polynomial* xsh_polynomial_new ( const cpl_polynomial *  pol  ) 

Create a polynomial.

Parameters:
pol The 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().

polynomial* xsh_polynomial_new_zero ( int  dim  ) 

Create a zero polynomial.

Parameters:
dim Dimension 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().

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

Rescale a polynomial.

Parameters:
p The polynomial to rescale
varno Rescale with respect to this variable (number)
scale The 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().

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

Shift a polynomial.

Parameters:
p The polynomial to shift
varno Shift with respect to this variable (number)
shift The 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().

double xsh_polynomial_solve_1d ( const polynomial p,
double  value,
double  guess,
int  multiplicity 
)

Solve p(x) = value.

Parameters:
p The input polynomial
value The requested value of the polynomial
guess A guess solution
multiplicity The 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().

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:
p The input polynomial
value The requested value of the polynomial
guess A guess solution
multiplicity The multiplycity of the root (or 1 if unknown)
varno The variable number to fix (1 or 2)
x_value Variable 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().


Generated on 13 Mar 2013 for X-shooter Pipeline Reference Manual by  doxygen 1.6.1