stormm::stmath::LogScaleSpline< T4 > Class Template Reference

A logarithmic spline can be very useful for interpolating functions that are steepest at low values of the argument, provided that the argument is never negative. This is a useful class of functions for describing inter-atomic potentials. The strategy is to utilize the logarithmic nature (and IEEE format) of a floating point number, taking the highest N bits of the mantissa and the exponent as an unsigned integer (because measurements of absolute distance will never be negative, the highest bit (the sign bit) will always be set to zero). It is most useful if the square root operation can be avoided altogether, indexing the table by the square of the function argument. This creates a more accurate table as well as saving arithmetic, although obtaining function derivatives (as a function of the argument, not its square) from the table becomes more expensive. In fact, this object abandons continuous derivatives in the tables and instead splines the derivative of the desired function as a separate logarithmic table. More...

#include <log_scale_spline.h>

Public Member Functions
LogSplineForm	getForm () const
	Get the target form of the function represented by the table.
TableIndexing	getIndexingMethod () const
	Get the method of indexing the table, an expression based on the target function's argument, e.g. the squared distance.
BasisFunctions	getBasisSet () const
	Get the basis functions used to construt each spline.
int	getBitStride () const
	Get the number of leading bits in the mantissa used to determine the array index.
int	getSplineDensity () const
	Get the number of spline segments per stride. This is two raised to the power of the result of getBitStride().
double	getEwaldCoefficient () const
	Get the Ewald coefficient in use for this spline table. A check will be made to ensure that the spline is of the proper type to have a valid Ewald coefficient.
double	getCoulombConstant () const
	Get the value of Coulomb's constant in use by the spline. A check will be made to ensure that the spline is of the proper type to have a valid Coulomb constant.
double	getMaximumRange () const
	Get the maximum range of the spline.
double	getMinimumRange () const
	Get the minimum absolute range of the spline.
float	getIndexingOffset () const
	Get the indexing offset.
int	getOptimizationDepth () const
	Get the optimization depth.
int	getSplineIndex (double r) const
	Get the spline index for a particular value of the argument of the tabulated function which has already been transformed to meet the object's indexing system.
int	getSplineIndexByRealArg (double r) const
	Get the spline index for a particular value of the argument of the tabulated function. Transformation of the input will occur internally based on how the object indexes its internal spline table, in a manner consistent with the object's precision model.
double	interpolateByValue (double r) const
	Get the value of the underlying function based on a value of the function argument. This accessor will throw a warning or an error if trying to access the a table built to be accessed using the squared value of the function.
double	interpolateBySquaredValue (double r2) const
	Get the value of the underlying function based on a squared value of the function argument. This accessor will throw a warning or an error if trying to access the a table built to be accessed using the value of the function.
double	evaluate (double r) const
	Evaluate the underlying function represented by the spline at a point expressed in the object's native indexing system (meaning, if the object indexes by the squared argument of the underlying function, then the input will reflect r^2 rather than r).
double	evaluateByRealArg (double r) const
	Evaluate the underlying function represented by the spline at a point on the natural axis of the underlying function. Transformation of this argument will be handled internally, and in a manner that reflects the object's precision model, before returning the result.
const LogSplineTable< T4 >	data (HybridTargetLevel tier=HybridTargetLevel::HOST) const
	Get the object's abstract for the CPU host or GPU device in either of two precision modes.
const LogSplineTable< void >	templateFreeData (HybridTargetLevel tier=HybridTargetLevel::HOST) const
	Get the object's abstract with templating removed.
const LogScaleSpline< T4 > *	getSelfPointer () const
	Get a pointer to the original object.
void	setMinimumSignificantRange (double min_range_in)
	Set the minimum significant range. This is purely for error analysis and will not affect the array indexing or other details of the spline. The value is set to 0.5 at initialization.
	LogScaleSpline (LogSplineForm target_form_in, double ewald_coefficient_in, double coulomb_constant_in=amber_ancient_bioq, int mantissa_bits_in=default_logtab_mantissa_bits, double max_range_in=default_logtab_max_range, double min_range_in=default_logtab_min_range, TableIndexing indexing_method_in=TableIndexing::SQUARED_ARG, BasisFunctions basis_set_in=BasisFunctions::POLYNOMIAL, int ulp_optimization_depth_in=2, float indexing_offset_in=0.0, ExceptionResponse policy=ExceptionResponse::DIE)
	The constructor needs an indication of the functional form to render. The number of bits will be decided by the data type if not indicated by the developer. Interpolation is fixed at cubic, for simplicity and speed. Additional input may be used to specify a particular function to spline.
	LogScaleSpline (LogSplineForm target_form_in, const std::vector< std::vector< double2 > > &custom_form_in, int mantissa_bits_in=default_logtab_mantissa_bits, double max_range_in=default_logtab_max_range, double min_range_in=default_logtab_min_range, TableIndexing indexing_method_in=TableIndexing::SQUARED_ARG, BasisFunctions basis_set_in=BasisFunctions::POLYNOMIAL, int ulp_optimization_depth_in=2, float indexing_offset_in=0.0, ExceptionResponse policy=ExceptionResponse::WARN)
	LogScaleSpline (const LogScaleSpline &original)=default
	With no pointers to repair and no const members, the default copy and move constructors as well as assignment operators are all valid.
	LogScaleSpline (LogScaleSpline &&original)=default
LogScaleSpline &	operator= (const LogScaleSpline &original)=default
LogScaleSpline &	operator= (LogScaleSpline &&original)=default
double3	getErrorEstimate () const
	Get the estimated error as a function of the distance at which the splines are evaluated. Mean error is returned in the "x" member of the tuple while standard deviation about the mean error is given in the "y" member of the tuple. The maximum and error value is returned in the tuple's "z" member.
double3	getErrorEstimate (double r) const

Detailed Description

template<typename T4>
class stormm::stmath::LogScaleSpline< T4 >

A logarithmic spline can be very useful for interpolating functions that are steepest at low values of the argument, provided that the argument is never negative. This is a useful class of functions for describing inter-atomic potentials. The strategy is to utilize the logarithmic nature (and IEEE format) of a floating point number, taking the highest N bits of the mantissa and the exponent as an unsigned integer (because measurements of absolute distance will never be negative, the highest bit (the sign bit) will always be set to zero). It is most useful if the square root operation can be avoided altogether, indexing the table by the square of the function argument. This creates a more accurate table as well as saving arithmetic, although obtaining function derivatives (as a function of the argument, not its square) from the table becomes more expensive. In fact, this object abandons continuous derivatives in the tables and instead splines the derivative of the desired function as a separate logarithmic table.

The process generates 2^N spline segments in the ranges [0, 2^-k), [2^-k, 2^(1-k)), [2^(1-k), 2^(2-k)), and so on for all k representable by floating point format's exponent. For N=5, there are 32 spline segments covering the ranges [1/4, 1/2), [1/2, 1), [1, 2), [2, 4), and so on. While a great deal of the table is spent covering infinitesimal increments over very negative powers of 2, the quantity of such numbers is limited by the size of the exponent (256 for 32-bit floats and 2048 for 64-bit floats in IEEE format), and these values are hardly ever accessed. For N = 5 in 32-bit floats, the cubic spline coefficients occupy 128kB of space, of which splines to cover the range [0.5, 16.0) occupy 2.5kB. For N = 8 in 64-bit floats, the cubic spline coefficients occupy 8MB of space and splines to cover the range [0.5, 16.0) occupy 40kB. The latter may be of use on CPU resources with higher cache, or in GPU contexts where caching can be well managed, but the former is quite useful in many GPU cases.

Constructor & Destructor Documentation

LogScaleSpline() [1/2]

template<typename T4>

stormm::stmath::LogScaleSpline< T4 >::LogScaleSpline	(	LogSplineForm	target_form_in,
		double	ewald_coefficient_in,
		double	coulomb_constant_in = amber_ancient_bioq,
		int	mantissa_bits_in = default_logtab_mantissa_bits,
		double	max_range_in = default_logtab_max_range,
		double	min_range_in = default_logtab_min_range,
		TableIndexing	indexing_method_in = TableIndexing::SQUARED_ARG,
		BasisFunctions	basis_set_in = BasisFunctions::POLYNOMIAL,
		int	ulp_optimization_depth_in = 2,
		float	indexing_offset_in = 0.0,
		ExceptionResponse	policy = ExceptionResponse::DIE )

The constructor needs an indication of the functional form to render. The number of bits will be decided by the data type if not indicated by the developer. Interpolation is fixed at cubic, for simplicity and speed. Additional input may be used to specify a particular function to spline.

Parameters

custom_form_in	If provided, this collection of arrays will provide the known values of the function to be splined (in each tuple's "y" member) and the value of the function argument for which the function is known (in each tuple's "x" member)
max_range_in	This will translate into the maximum_range member variable, after some checking and refinement
min_range_in	This will translate into the minimum_absolute_range member variable, after some checking and refinement
policy	Indicate what to do in the event of bad input, i.e. if custom spline data is not able to fulfill the range requested

LogScaleSpline() [2/2]

template<typename T4>

stormm::stmath::LogScaleSpline< T4 >::LogScaleSpline ( const LogScaleSpline< T4 > & original )

default

With no pointers to repair and no const members, the default copy and move constructors as well as assignment operators are all valid.

Parameters

original	The existing object to copy or move
other	Another object placed on the right hand side of the assignment statement

Member Function Documentation

data()

template<typename T4>

const LogSplineTable< T4 > stormm::stmath::LogScaleSpline< T4 >::data

(

HybridTargetLevel

tier = HybridTargetLevel::HOST

)

const

Get the object's abstract for the CPU host or GPU device in either of two precision modes.

tier Indicate whether to retrieve pointers on the GPU device or CPU host

evaluate()

template<typename T4>

double stormm::stmath::LogScaleSpline< T4 >::evaluate

(

double

r

)

const

Evaluate the underlying function represented by the spline at a point expressed in the object's native indexing system (meaning, if the object indexes by the squared argument of the underlying function, then the input will reflect r^2 rather than r).

Parameters

r	Argument to the underlying function, transformed as appropriate for indexing

evaluateByRealArg()

template<typename T4>

double stormm::stmath::LogScaleSpline< T4 >::evaluateByRealArg

(

double

r

)

const

Evaluate the underlying function represented by the spline at a point on the natural axis of the underlying function. Transformation of this argument will be handled internally, and in a manner that reflects the object's precision model, before returning the result.

Parameters

r	Argument to the underlying function

getErrorEstimate()

template<typename T4>

double3 stormm::stmath::LogScaleSpline< T4 >::getErrorEstimate

(

)

const

Get the estimated error as a function of the distance at which the splines are evaluated. Mean error is returned in the "x" member of the tuple while standard deviation about the mean error is given in the "y" member of the tuple. The maximum and error value is returned in the tuple's "z" member.

Overloaded:

• Get the overall error estimate
• Get the error estimate for the spline segment comprising a particular value of distance

Parameters

r	The distance of interest

getSplineIndex()

template<typename T4>

int stormm::stmath::LogScaleSpline< T4 >::getSplineIndex

(

double

r

)

const

Get the spline index for a particular value of the argument of the tabulated function which has already been transformed to meet the object's indexing system.

Parameters

r	The argument to the tabulated function. The exact meaning will be interpreted based on the table's internal indexing_method setting.

getSplineIndexByRealArg()

template<typename T4>

int stormm::stmath::LogScaleSpline< T4 >::getSplineIndexByRealArg

(

double

r

)

const

Get the spline index for a particular value of the argument of the tabulated function. Transformation of the input will occur internally based on how the object indexes its internal spline table, in a manner consistent with the object's precision model.

Parameters

r	The argument to the tabulated function, expressed on its natural axis

interpolateBySquaredValue()

template<typename T4>

double stormm::stmath::LogScaleSpline< T4 >::interpolateBySquaredValue

(

double

r2

)

const

Get the value of the underlying function based on a squared value of the function argument. This accessor will throw a warning or an error if trying to access the a table built to be accessed using the value of the function.

Parameters

r2	The squared value at which to evaluate the underlying function

interpolateByValue()

template<typename T4>

double stormm::stmath::LogScaleSpline< T4 >::interpolateByValue

(

double

r

)

const

Get the value of the underlying function based on a value of the function argument. This accessor will throw a warning or an error if trying to access the a table built to be accessed using the squared value of the function.

Parameters

r	The value of at which to evaluate the underlying function

setMinimumSignificantRange()

template<typename T4>

void stormm::stmath::LogScaleSpline< T4 >::setMinimumSignificantRange

(

double

min_range_in

)

Set the minimum significant range. This is purely for error analysis and will not affect the array indexing or other details of the spline. The value is set to 0.5 at initialization.

Parameters

min_range_in

The minimum range to set

---

The documentation for this class was generated from the following file:

• src/Math/log_scale_spline.h