Memory structure and interfaces for rpolator interpolation code. More...

This graph shows which files directly or indirectly include this file:

Data Structures
struct	cubic_params
	Cubic spline interpolation (natural cubic splines = scheme 3, clampled cubic splines = scheme 4) More...

struct	rpol_table
	Structure describing an interpolation table, interpolation scheme and selected options. More...

Macros
#define	WITH_RPOLATOR 1

Typedefs
typedef struct cubic_params	CsplinePar

typedef struct rpol_table	RpolTable

Functions
struct rpol_table *	read_rpol1d_table (const char *fn)
	Simplified version for loading a 1-d table with two columns. More...

struct rpol_table *	read_rpol2d_table (const char fn, const char ymarker)
	Simplified version for loading a 2-d table 1+ny columns (ny=available y values in header line). More...

struct rpol_table *	read_rpol3d_table (const char *fn)
	Simplified version for loading a 2-d table with x/y/z in three columns (x/y intervals rectangular). More...

struct rpol_table *	read_rpol_table (const char fname, int nd, const char ymarker, const char *options)
	General function for loading interpolation table combines 1-D and 2-D grid case. More...

int	read_table (const char fname, int maxrow, double col1, double *col2)
	Low-level reading of 2-column data tables up to given number of data rows. More...

int	read_table2 (const char fname, int maxrow, double col1, double *col2)

int	read_table3 (const char fname, int maxrow, double col1, double col2, double col3)
	read_table3() and so on have more columns than read_table but are still only suitable for 1-D interpolation. More...

int	read_table4 (const char fname, int maxrow, double col1, double col2, double col3, double *col4)

int	read_table5 (const char fname, int maxrow, double col1, double col2, double col3, double col4, double col5)

int	read_table_v (const char fname, FILE fptr, size_t nrow, size_t ncol, double *col, const size_t selcol)
	Read tables any length (up to some ridiculous maximum) with the requested columns either in natural order or picking columns as requested. More...

double	rpol (double x, double y, int n, double xp)
	Linear interpolation with binary search algorithm. More...

double	rpol_2d_linear (double x, double y, double *z, int nx, int ny, double xp, double yp, int eq, int clip)
	Linear interpolation in 2-D.

double	rpol_2nd_order (double x, double y, int n, double xp, int eq, int clip)
	Second/third order interpolation in 1-D with clipping option outside range. More...

void	rpol_check_equi_range (struct rpol_table *rpt)

double	rpol_cspline (double x, double y, const CsplinePar *csp, int n, double xp, int eq, int clip)
	Cubic spline interpolation in 1-D with clipping option outside range. More...

void	rpol_free (struct rpol_table *rpt, int removing)
	Free a previously allocated interpolation table data structure. More...

void	rpol_info (struct rpol_table *rpt)
	Show information about given interpolation table.

void	rpol_info_lvl (struct rpol_table *rpt, int lvl)
	Report table info at given temporary verbosity level.

int	rpol_is_verbose (void)
	Report what verbosity level is set for the rpolator code.

double	rpol_linear (double x, double y, int n, double xp, int eq, int clip)
	Linear interpolation in 1-D with with either direct access for equidistant table or with binary search algorithm. More...

double	rpol_nearest (double x, double y, int n, double xp, int eq, int clip)
	Nearest value (not actually interpolation) in 1-D with with either direct access for equidistant table or with binary search algorithm. More...

int	rpol_set_verbose (int lvl)
	Set the verbosity level for the rpolator code, return old level.

double	rpolate (struct rpol_table *rpt, double x, double y, int scheme)
	High-level interpolation function (user code only has to keep a pointer to the allocated object) generic for 1-D and 2-D tables. More...

double	rpolate_1d (struct rpol_table *rpt, double x, int scheme)
	High-level interpolation function (user code only has to keep a pointer to the allocated object) limited to 1-D table interpolation. More...

double	rpolate_1d_lin (struct rpol_table *rpt, double x)
	High-level interpolation function (user code only has to keep a pointer to the allocated object) limited to 1-D table interpolation, with linear interpolation scheme hard-wired (independent of any '#@RPOL@' header line). More...

double	rpolate_2d (struct rpol_table *rpt, double x, double y, int scheme)
	High-level interpolation function (user code only has to keep a pointer to the allocated object) limited to 2-D table interpolation. More...

CsplinePar *	set_1d_cubic_params (double x, double y, int n, int clamped)
	Set up cubic spline parameters for n-1 intervals resulting from n data points. More...

struct rpol_table *	simple_rpol1d_table (const char label, double x, double *y, int n, int clip)
	A simplified way of setting up a 1-D rpol table for local use, without reading any files. More...

Detailed Description

Author: Konrad Bernloehr

Date

2017

CVS $Date: 2019/01/15 16:34:16 $

Version

CVS $Revision: 1.11 $

Function Documentation

◆ read_rpol1d_table()

struct rpol_table* read_rpol1d_table ( const char * fn )

The text free format input file is expected to contain (at least) two columns for x and y values. Any further columns are ignored. Comment and empty lines are ignored as well.

References read_rpol_table().

◆ read_rpol2d_table()

struct rpol_table* read_rpol2d_table	(	const char *	fn,
		const char *	ymarker
	)

The text input file is expected to contain a header line where, following the given marker text, the y values to which the following values correspond are listed. The number ny of distinct, ascending-order values in that line defines the number of z expected in the following data lines. The x value is the first value in each data line. If a data line contains more than 1+ny values the extra values are ignored. Comment (except header line) and empty lines are ignored.

References read_rpol_table().

◆ read_rpol3d_table()

struct rpol_table* read_rpol3d_table ( const char * fn )

Functionally equivalent to read_rpol2d_table() but the y values are not given just once in a specially marked header line but repeated as the second value in each line. Instead of one header line plus nx data lines with 1+ny values the input to this function is expected to contain nx*ny lines with three values each. While x and y values do not need to be equidistant, they are required to match a rectangular grid, with the same distinct, ascending-order y values appearing for each x value and the same distinct, ascending-order x values appearing for each y value, eather as x1/y1/z11, x2/y1/z21, ... or x1/y/z11, x1/y2/z12, ...

References read_rpol_table().

◆ read_rpol_table()

struct rpol_table* read_rpol_table	(	const char *	fname,
		int	nd,
		const char *	ymarker,
		const char *	options
	)

Parameters

fname	Text input file name
nd	dimension/format parameter with the following possible values: 1: 1-D (2-column) input expected, 2: 2-D (1+ny columns) input with marker indicating special line for y values, 3: 2-D (3 columns) with repeated x and y values (matching rectangular grid), 0: format entirely defined in the data file, requiring the first line to start as '#@RPOL@', -1,-2,-3: If the first line starts as '#@RPOL@', this line defines the format and otherwise it is falling back to format 1, 2, or 3, respectively.
ymarker	The marker indicating the special header line listing the y values with nd=2 only (otherwise ignored).

Here is the caller graph for this function:

◆ read_table()

int read_table	(	const char *	fname,
		int	maxrow,
		double *	col1,
		double *	col2
	)

Parameters

fname	Name of file to be opened.
maxrow	Maximum number of (non-empty, non-comment) rows of data to read.
col1	Array where values of column 1 are to be copied to.
col2	Array where values of column 2 are to be copied to.

Returns: Number of data rows read (usable values in col1 and col2) or -1 (error).

◆ read_table3()

int read_table3	(	const char *	fname,
		int	maxrow,
		double *	col1,
		double *	col2,
		double *	col3
	)

◆ read_table_v()

int read_table_v	(	const char *	fname,
		FILE *	fptr,
		size_t *	nrow,
		size_t	ncol,
		double ***	col,
		const size_t *	selcol
	)

All data areas are dynamically allocated (and must be fresh beforehand).

On memory allocation errors a -1 error code is returned but already allocated parts are not released and the file may still be opened.

Parameters

fname	Name or URL of file to read. @paran fptr File pointer if file already open or NULL if fname has to be opened.
nrow	Pointer to number of rows with valid data (pass address of a size_t variable). Input value used to guide initial allocation, not fixing actual rows to read.
ncol	Number of columns of data requested to be read.
col	Pointer to where pointers to column-wise data get allocated. (Need to pass address of a double ** variable.)
selcol	NULL for natural column order or pointer to ncol (natural, >=1) column numbers in selected order. Example: { 1, 7, 5 } will place data from the first column under (col)[0], data from the seventh column under (col)[1], and data from the fifth column under (*col)[2].

Returns: 0 (OK), -1 (memory error), -2 (invalid parameter), -3 (asking for too many columns), -4 (too many rows of data, stopped reading).

◆ rpol()

double rpol	(	double *	x,
		double *	y,
		int	n,
		double	xp
	)

Linear interpolation between data point in sorted (i.e. monotonic ascending or descending) order. The resulting interpolated value is returned as a return value. This is the old-style function without any option for equidistant support points or clipping. Note that rpol(px,py,n,xp) is the same as rpol_linear(px,py,n,xp,0,0).

This function calls interp() to find out where to interpolate.

Parameters

x	Input: Coordinates for data table
y	Input: Corresponding values for data table
n	Input: Number of data points
xp	Input: Coordinate of requested value

Returns: Interpolated value

References interp(), rpol_table::x, and rpol_table::y.

◆ rpol_2nd_order()

double rpol_2nd_order	(	double *	x,
		double *	y,
		int	n,
		double	xp,
		int	eq,
		int	clip
	)

Second to third order interpolation in 1-D with with either direct access for equidistant table or with binary search algorithm. Instead of third order Lagrange interpolation it uses left- and right-sided 2nd order interpolation and a weighted mean between the two variants, rendering it effectively third order except for the intervals next to borders where it degenerates to 2nd order.

Higher-order interpolation between data point in sorted (i.e. monotonic ascending or descending) order. The resulting interpolated value is returned as a return value. If the table is known to be provided at equidistant supporting points, direct access is preferred. Otherwise a binary search algorithm is used to find the proper interval. Since there is no initialization phase, this is actually slower than the cubic spline interpolation.

This function calls interp() to find out where to interpolate.

Parameters

x	Input: Coordinates for data table
y	Input: Corresponding values for data table
n	Input: Number of data points
xp	Input: Coordinate of requested value
eq	Input: If non-zero: table is at equidistant points.
clip	Input: Zero: no clipping; extrapolate with left/right edge value outside range. Non-zero: clip at edges; return 0. outside supported range.

Returns: Interpolated value

References rpol_table::dxi, interp(), rpol_linear(), rpol_table::x, and rpol_table::y.

◆ rpol_cspline()

double rpol_cspline	(	double *	x,
		double *	y,
		const CsplinePar *	csp,
		int	n,
		double	xp,
		int	eq,
		int	clip
	)

Cubic spline interpolation in 1-D with with either direct access for equidistant table or with binary search algorithm.

Quadratic interpolation between data point in sorted (i.e. monotonic ascending or descending) order. The resulting interpolated value is returned as a return value. If the table is known to be provided at equidistant supporting points, direct access is preferred. Otherwise a binary search algorithm is used to find the proper interval. Because of the overhead of calculating the cubic spline parameters, those have to be initialized before the interpolation can be used. Initialisation has to be for either natural or clampled cubic splines.

This function calls interp() to find out where to interpolate.

Parameters

x	Input: Coordinates for data table
y	Input: Corresponding values for data table
csp	Input: Cubic spline parameters (a,b,c,d) for each of n-1 intervals
n	Input: Number of data points
xp	Input: Coordinate of requested value
eq	Input: If non-zero: table is at equidistant points.
clip	Input: Zero: no clipping; extrapolate with left/right edge value outside range. Non-zero: clip at edges; return 0. outside supported range.

Returns: Interpolated value

References interp(), and rpol_linear().

Here is the caller graph for this function:

◆ rpol_free()

void rpol_free	(	struct rpol_table *	rpt,
		int	removing
	)

This is dangerous to used if the pointer is used in more than one place! Keep in mind that each time you ask to load the same table again you will just get a copy of the same pointer again. If that could be the case you better don't force deleting the structure itself.

References rpol_table::csp, rpol_table::fname, rpol_table::options, rpol_table::use_count, rpol_table::x, rpol_table::y, rpol_table::z, rpol_table::zxmax, and rpol_table::zxmin.

◆ rpol_linear()

double rpol_linear	(	double *	x,
		double *	y,
		int	n,
		double	xp,
		int	eq,
		int	clip
	)

Linear interpolation between data point in sorted (i.e. monotonic ascending or descending) order. The resulting interpolated value is returned as a return value. If the table is known to be provided at equidistant supporting points, direct access is preferred. Otherwise a binary search algorithm is used to find the proper interval.

This function calls interp() to find out where to interpolate.

Parameters

x	Input: Coordinates for data table
y	Input: Corresponding values for data table
n	Input: Number of data points
xp	Input: Coordinate of requested value
eq	Input: If non-zero: table is at equidistant points.
clip	Input: Zero: no clipping; extrapolate with left/right edge value outside range. Non-zero: clip at edges; return 0. outside supported range.

Returns: Interpolated value

References rpol_table::dxi, interp(), rpol_table::x, and rpol_table::y.

Here is the caller graph for this function:

◆ rpol_nearest()

double rpol_nearest	(	double *	x,
		double *	y,
		int	n,
		double	xp,
		int	eq,
		int	clip
	)

Take the nearest data point in sorted (i.e. monotonic ascending [no descending yet]) order. The selected value is returned as a return value. If the table is known to be provided at equidistant supporting points, direct access is preferred. Otherwise a binary search algorithm is used to find the proper interval.

This function calls interp() to find out where to interpolate.

Parameters

x	Input: Coordinates for data table
y	Input: Corresponding values for data table
n	Input: Number of data points
xp	Input: Coordinate of requested value
eq	Input: If non-zero: table is at equidistant points.
clip	Input: Zero: no clipping; extrapolate with left/right edge value outside range. Non-zero: clip at edges; return 0. outside supported range.

Returns: Nearest value

References rpol_table::dxi, interp(), rpol_table::x, and rpol_table::y.

◆ rpolate()

double rpolate	(	struct rpol_table *	rpt,
		double	x,
		double	y,
		int	scheme
	)

Parameters

rpt	Pointer to interpolation table structure, previously set up with read_rpol_table. Keep in mind that it gets only allocated once and, if you want to free it, you should not free it more than once. In the case of this function, it can represent either a 1-D or 2-D table.
x	The x coordinate value at which the 1-D or 2-D table is to be interpolated.
y	The y coordinate value at which a 2-D table is to be interpolated (ignored for 1-D). If non-zero for 1-D tables, a warning may be issued.
scheme	Interpolation scheme: 0 ... 4 (not all implemented) for a specific user-defined scheme or -1 (or other values outside of [0:4] range) for the scheme determined when the table was read and allocated.

◆ rpolate_1d()

double rpolate_1d	(	struct rpol_table *	rpt,
		double	x,
		int	scheme
	)

Parameters

rpt	Pointer to interpolation table structure, previously set up with read_rpol_table. Keep in mind that it gets only allocated once and, if you want to free it, you should not free it more than once. In the case of this function, it should represent a 1-D table.
x	The x coordinate (abscissa) value at which the 1-D table is to be interpolated.
scheme	Interpolation scheme: 0 ... 4 for a specific user-defined scheme or -1 (or other values outside of [0:4] range) for the scheme determined when the table was read and allocated. For 2-D tables for which an upper envelope in x projection was requested a -1 scheme will interpolate in this upper envelope and -2 the lower envelope.

Here is the caller graph for this function:

◆ rpolate_1d_lin()

double rpolate_1d_lin	(	struct rpol_table *	rpt,
		double	x
	)

This is the most direct equivalence to the older rpol() function.

Parameters

rpt	Pointer to interpolation table structure, previously set up with read_rpol_table. Keep in mind that it gets only allocated once and, if you want to free it, you should not free it more than once. In the case of this function, it should represent a 1-D table.
x	The x coordinate (abscissa) value at which the 1-D table is to be interpolated.

References rpolate_1d().

◆ rpolate_2d()

double rpolate_2d	(	struct rpol_table *	rpt,
		double	x,
		double	y,
		int	scheme
	)

Fall-back to 1-D only after issueing a warning.

Parameters

rpt	Pointer to interpolation table structure, previously set up with read_rpol_table. Keep in mind that it gets only allocated once and, if you want to free it, you should not free it more than once. In the case of this function, it should represent a 2-D table.
x	The x coordinate value at which the 2-D table is to be interpolated.
y	The y coordinate value at which the 2-D table is to be interpolated (ignored for 1-D).
scheme	Interpolation scheme: 0 ... 4 (not all implemented) for a specific user-defined scheme or -1 (or other values outside of [0:4] range) for the scheme determined when the table was read and allocated.

References rpol_table::fname, rpol_table::ndim, and rpolate_1d().

◆ set_1d_cubic_params()

CsplinePar* set_1d_cubic_params	(	double *	x,
		double *	y,
		int	n,
		int	clamped
	)

The resulting cubic spline can either be a 'natural' one (second derivative is zero at the edges) or a clamped one (first derivative is fixed, currently to zero, at the edges).

Parameters

x	Input: Coordinates for data table
y	Input: Corresponding values for data table
n	Input: Number of data points
clamped	Input: 0 (natural cubic spline) or 1 (clamped cubic spline)

Returns: Allocated array of four parameters each defining the third order polynomial in each interval. In case of invalid input parameters a NULL pointer is returned.

References cubic_params::d, and rpol_table::x.

Here is the caller graph for this function:

◆ simple_rpol1d_table()

struct rpol_table* simple_rpol1d_table	(	const char *	label,
		double *	x,
		double *	y,
		int	n,
		int	clip
	)

The returned pointer is also not hooked into the global linked list, thus is supposed to be safe to be removed after use.

References rpol_table::clipping, rpol_table::fname, rpol_table::ndim, rpol_table::ny, rpol_table::scheme, rpol_table::use_count, rpol_table::x, rpol_table::y, and rpol_table::z.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Function Documentation

◆ read_rpol1d_table()

◆ read_rpol2d_table()

◆ read_rpol3d_table()

◆ read_rpol_table()

◆ read_table()

◆ read_table3()

◆ read_table_v()

◆ rpol()

◆ rpol_2nd_order()

◆ rpol_cspline()

◆ rpol_free()

◆ rpol_linear()

◆ rpol_nearest()

◆ rpolate()

◆ rpolate_1d()

◆ rpolate_1d_lin()

◆ rpolate_2d()

◆ set_1d_cubic_params()

◆ simple_rpol1d_table()