LiSK - Library for Evaluating Classical Polylogarithms and Li_22. More...

Classes
struct	constants
	Constants. More...

Public Member Functions
	LiSK (const size_t n=4, const size_t prec=34)
	C'stor. More...

numtype	Li22 (const numtype x, const numtype y)
	Li22(x,y) More...


numtype	Li (const size_t n, const numtype x)
	Li(n,x) More...

numtype	Li1 (const numtype x)
	Li(n,x) More...

numtype	Li2 (const numtype x)
	Li(n,x) More...

numtype	Li3 (const numtype x)
	Li(n,x) More...

numtype	Li4 (const numtype x)
	Li(n,x) More...

Private Member Functions
bool	_ErrorEstimate (const numtype &res, const numtype &prev_res, const numtype &current) const
	ErrorEstimate. More...

void	_init (const std::unordered_map< std::string, size_t > max_values)
	Initialise constants. More...

numtype	convert (const cln::cl_R &x) const
	Convert CLN to desired type. More...

template<typename T >
T	_vec_max (std::vector< T > v) const
	Maximum of vector entries. More...

void	_HarmNum_extend ()
	Extend Harmonic numbers. More...

void	_PosZeta_extend ()
	Extend positve Zeta values. More...

void	_Factorials_extend ()
	Extend factorials. More...

void	_BernNum_extend ()
	Extend Bernoulli numbers. More...

void	_NegZeta_extend ()
	Negative zeta values. More...

void	_LiCij_extend ()
	Extend Li constants LiCij. More...

void	_LiBn_eq59_extend ()
	Extend Li constants LiBn_eq59. More...

numtype	_Lin_1mexpal (const size_t n, const numtype &x)
	Li_n(1-exp(-alpha)) More...

numtype	_Li_sumBn (const numtype &precal, const numtype &al, const size_t n, const bool fac_2n=false, const bool sign=false)
	Li sums. More...

numtype	_Lin_basis (const size_t n, const numtype &x)
	General Li_n(x) More...

numtype	_Lin_inverse (const size_t n, const numtype &x)
	Inversion formula for Li(n,x) More...

numtype	_Lin_expal (const size_t n, const numtype &x)
	All order Li_n(exp(-alpha)) More...

numtype	Pow (const numtype &x, const int n) const
	Power function. More...

bool	is_zero (const numtype &x) const
	Is_zero. More...

numtype	_add_iep (const numtype &x) const
	Add imaginary part. More...

cln::cl_N	_adjustDigits (const cln::cl_N &x) const
	Adjust digits. More...

numtype	_Li22 (const numtype &x, const numtype &y)
	Li22(x,y) More...

numtype	_Li22_orig (const numtype &x, const numtype &y) const
	Original Li22(x,y) More...

numtype	_Li22_stuffle (const numtype &x, const numtype &y)
	Stuffle relation for Li22(x,y) More...

numtype	_Li22_inversion (const numtype &x, const numtype &y)
	Inversion relation for Li22(x,y) More...


cln::cl_R	Re (const cln::cl_N &x) const
	Real part. More...

double	Re (const std::complex< double > &x) const
	Real part. More...


numtype	_Li1 (const numtype &x)
	Li(n,x) More...

numtype	_Li2 (const numtype &x)
	Li(n,x) More...

numtype	_Li3 (const numtype &x)
	Li(n,x) More...

numtype	_Li4 (const numtype &x)
	Li(n,x) More...

Private Attributes
const unsigned	_step = 5
	Step size. More...

const bool	_cln_tofloat = false
	Enable/disable floating point conversion of constants. More...

const std::unordered_map< std::string, size_t >	_user_max_values
	User defined upper limits for various constants. More...

const size_t	_prec
	Precision value. More...


const int	_offset = 2
	Small positive imaginary part. More...

const cp_d	_iep_d
	Small positive imaginary part. More...

const cln::cl_N	_iep_clN
	Small positive imaginary part. More...


constants< numtype >	_constants

constants< cln::cl_R >	_constants_clR

Detailed Description

template<typename numtype>
class LiSK::LiSK< numtype >

LiSK - Library for Evaluating Classical Polylogarithms and Li_22.

Note: A lightweight library for evaluating classical polylogarithms Li_n and the special function Li_{22} based on arXiv:1601.02649. Currently a double precision as well as an arbitrary precision implementation is available; the latter through the CLN library by Bruno Haible ( http://www.ginac.de/CLN/ ). CLN is an essential part of this library and is also used in the initialisation phase of the double prescision implementation.; Although this library is header-only the actual implementation is stored in lisk.cpp which is included at the end of lisk.hpp.

Constructor & Destructor Documentation

◆ LiSK()

template<typename numtype >

LiSK::LiSK< numtype >::LiSK	(	const size_t	n = `4`,
		const size_t	prec = `34`
	)

C'stor.

Note: During initialisation (construction) constants for polylogarithms up to weight n are computed. Occurences of polylogarithms with higher weights during runtime are possible but might lead to longer evaluation times due to adaption of the constants. If weights n>4 are expected to occur n should be specified accordingly to reduce evaluation time during the actual computation. If CLN is used for arbitrary precision then the desired precision is set with prec.

Parameters

n	Prepare for polylogs of weight n
prec	Set precision when using CLN

Member Function Documentation

◆ _add_iep()

template<typename numtype >

numtype LiSK::LiSK< numtype >::_add_iep ( const numtype & x ) const

private

Add imaginary part.

Note: Add small imaginary part depending on precision. We follow the widely used convention for mathematical software, e.g. "The C Standard", Mathematica, GiNaC, etc.

Parameters

x	Complex value

Returns: x-iep

◆ _adjustDigits()

template<typename numtype >

cln::cl_N LiSK::LiSK< numtype >::_adjustDigits ( const cln::cl_N & x ) const

inlineprivate

Adjust digits.

Note: Adjust digits of input variables such that they fullfil desired precision. Only relevant for arbitrary precision part.

Parameters

x	Complex value

Returns: x adjusted to prec digits

◆ _BernNum_extend()

template<typename numtype >

void LiSK::LiSK< numtype >::_BernNum_extend ( )

private

Extend Bernoulli numbers.

Note: Extends BernNum vector B_n with n=0,1,2,3,... . B_n=0 for odd n>1. Zeros are kept for now. If that poses a performance or memory problem later on it could be changed.

◆ _ErrorEstimate()

template<typename numtype >

bool LiSK::LiSK< numtype >::_ErrorEstimate	(	const numtype &	res,
		const numtype &	prev_res,
		const numtype &	current
	)		const

private

ErrorEstimate.

Note: Try to estimate how far we have to expand to get the required precision. Use practical approach as also used in GiNaC, i.e. check if new result differs from previous one. Due to included zeros in the constants we need to check for them.

Parameters

res	Latest computed result
prev_res	In previous step computed result
current	Check current if zero

Returns: True, if res!=prev_res || tmp==0. False otherwise

◆ _Factorials_extend()

template<typename numtype >

void LiSK::LiSK< numtype >::_Factorials_extend ( )

private

Extend factorials.

Note: Extends Factorials vector n! with n=0,1,2,...

◆ _HarmNum_extend()

template<typename numtype >

void LiSK::LiSK< numtype >::_HarmNum_extend ( )

private

Extend Harmonic numbers.

Note: Extends HarmNum vector up to nHarmNum, starting with H_0=0.

◆ _init()

template<typename numtype >

void LiSK::LiSK< numtype >::_init ( const std::unordered_map< std::string, size_t > max_values )

private

Initialise constants.

Parameters

max_values Map setting the maximum for each constant indicated by its key value. See constants::max_value

◆ _Li1()

template<typename numtype >

numtype LiSK::LiSK< numtype >::_Li1 ( const numtype & x )

private

Li(n,x)

Note: Classical polylogarithm of weight n at point x but no imaginary part is assigned

Parameters

n	Weight of classical polylogarithm
x	Point of evaluation

Returns: Li(n,x)

◆ _Li2()

template<typename numtype >

numtype LiSK::LiSK< numtype >::_Li2 ( const numtype & x )

private

Li(n,x)

Note: Classical polylogarithm of weight n at point x but no imaginary part is assigned

Parameters

n	Weight of classical polylogarithm
x	Point of evaluation

Returns: Li(n,x)

◆ _Li22()

template<typename numtype >

numtype LiSK::LiSK< numtype >::_Li22	(	const numtype &	x,
		const numtype &	y
	)

private

Li22(x,y)

Note: No imaginary parts will be assigned.

Parameters

x	Point of evaluation
y	Point of evaluation

Returns: Li22(x,y)

◆ _Li22_inversion()

template<typename numtype >

numtype LiSK::LiSK< numtype >::_Li22_inversion	(	const numtype &	x,
		const numtype &	y
	)

private

Inversion relation for Li22(x,y)

Parameters

x	Point of evaluation
y	Point of evaluation

Returns: Inversion relation from eq.(6.4)

◆ _Li22_orig()

template<typename numtype >

numtype LiSK::LiSK< numtype >::_Li22_orig	(	const numtype &	x,
		const numtype &	y
	)		const

private

Original Li22(x,y)

Note: Original definition of Li22(x,y) from (6.1) if |x|<1 and |xy|<1.

Parameters

x	Point of evaluation
y	Point of evaluation

Returns: Li22(x,y)

◆ _Li22_stuffle()

template<typename numtype >

numtype LiSK::LiSK< numtype >::_Li22_stuffle	(	const numtype &	x,
		const numtype &	y
	)

inlineprivate

Stuffle relation for Li22(x,y)

Parameters

x	Point of evaluation
y	Point of evaluation

Returns: -Li22(y,x) - Li4(x*y) + Li2(x)*Li2(y)

◆ _Li3()

template<typename numtype >

numtype LiSK::LiSK< numtype >::_Li3 ( const numtype & x )

private

Li(n,x)

Note: Classical polylogarithm of weight n at point x but no imaginary part is assigned

Parameters

n	Weight of classical polylogarithm
x	Point of evaluation

Returns: Li(n,x)

◆ _Li4()

template<typename numtype >

numtype LiSK::LiSK< numtype >::_Li4 ( const numtype & x )

private

Li(n,x)

Note: Classical polylogarithm of weight n at point x but no imaginary part is assigned

Parameters

n	Weight of classical polylogarithm
x	Point of evaluation

Returns: Li(n,x)

◆ _Li_sumBn()

template<typename numtype >

numtype LiSK::LiSK< numtype >::_Li_sumBn	(	const numtype &	precal,
		const numtype &	al,
		const size_t	n,
		const bool	fac_2n = `false`,
		const bool	sign = `false`
	)

private

Li sums.

Note: Compute Li_n(~al) = precal + sign * sum_{m=1} B_{2m}/(2m*(2m+n-1)!)*al^{2m+n-1} as needed for the classical polylogarithms (eq.(5.9)).

Parameters

precal	Terms to be added to sum
al	Accordingly mapped argument of Li_n(x). See eq.(5.9) and eq.(5.10)
n	Weight specifier Li_n
fac_2n	If true, each summand will be multiplied by 2m
sign	If true, the entire sum is multiplied by -1

Returns: Li_n(~al)

◆ _LiBn_eq59_extend()

template<typename numtype >

void LiSK::LiSK< numtype >::_LiBn_eq59_extend ( )

private

Extend Li constants LiBn_eq59.

Note: Compute the coefficients tBnm = B_{2n}/(2n*(2n+m)!) for n>0 and m=1,2,3

◆ _LiCij_extend()

template<typename numtype >

void LiSK::LiSK< numtype >::_LiCij_extend ( )

private

Extend Li constants LiCij.

Note: Compute the coefficients tCij = LiCij/(j+1)! from eq.(5.10). Extends the multi-dim vector LiCij containing tCij with i=1,2,3,4 and j=0,1,2,...

◆ _Lin_1mexpal()

template<typename numtype >

numtype LiSK::LiSK< numtype >::_Lin_1mexpal	(	const size_t	n,
		const numtype &	x
	)

private

Li_n(1-exp(-alpha))

Note: Implementation of eq.(5.10) up to desired accuracy.

Parameters

n	Weight of Li_n
x	Point of evaluation, i.e. x=1-exp(-alpha)

Returns: Li_n(x) up to desired accuracy.

◆ _Lin_basis()

template<typename numtype >

numtype LiSK::LiSK< numtype >::_Lin_basis	(	const size_t	n,
		const numtype &	x
	)

private

General Li_n(x)

Parameters

x	Point of evaluation
n	Weight of Li_n

Returns: Li_n(x)

◆ _Lin_expal()

template<typename numtype >

numtype LiSK::LiSK< numtype >::_Lin_expal	(	const size_t	n,
		const numtype &	x
	)

private

All order Li_n(exp(-alpha))

Note: Implementation of eq.(5.8) for all n>0.

Parameters

n	Weight specifier Li_n
x	Point of evaluation, i.e. x=exp(-alpha)

Returns: Li_n(x) up to desired accuracy

◆ _Lin_inverse()

template<typename numtype >

numtype LiSK::LiSK< numtype >::_Lin_inverse	(	const size_t	n,
		const numtype &	x
	)

private

Inversion formula for Li(n,x)

Note: Inversion formula from eq.(5.6). Used for Li_n with n>4.

Parameters

x	Point of evaluation
n	Weight of Li_n

Returns: Li_n(x) where |x|>1

◆ _NegZeta_extend()

template<typename numtype >

void LiSK::LiSK< numtype >::_NegZeta_extend ( )

private

Negative zeta values.

Note: Extends NegZeta vector with zeta(-n), n=1,2,3.... zeta(-n)=0 for even n>0. Zeros are kept for now.

◆ _PosZeta_extend()

template<typename numtype >

void LiSK::LiSK< numtype >::_PosZeta_extend ( )

private

Extend positve Zeta values.

Note: Extends PosZeta vector with zeta(n), n=0,1,2,... and zeta(1)=0.

◆ _vec_max()

template<typename numtype >

template<typename T >

T LiSK::LiSK< numtype >::_vec_max ( std::vector< T > v ) const

private

Maximum of vector entries.

Parameters

v	Vector from which maximal value is determined, e.g. {x1,x2}

Returns: Maximal value of v, e.g. x1 if x1>x2

◆ convert()

template<typename numtype >

numtype LiSK::LiSK< numtype >::convert ( const cln::cl_R & x ) const

private

Convert CLN to desired type.

Parameters

x	Value to be converted

Returns: x in desired type

◆ is_zero()

template<typename numtype >

bool LiSK::LiSK< numtype >::is_zero ( const numtype & x ) const

private

Is_zero.

Note: Using CLNs zerop() to determine if number is zero.

Parameters

x	Complex number

Returns: True, if x=0. False, otherwise

◆ Li()

template<typename numtype >

numtype LiSK::LiSK< numtype >::Li	(	const size_t	n,
		const numtype	x
	)

Li(n,x)

Note: Classical polylogarithm of weight n at point x. Public wrapper for the actual private implementation. A small imaginary part is assigned, i.e. x->x+iep. For the n<=4 the abbreviations Lin(x)=Li(n,x) are supported.

Parameters

n	Weight of classical polylogarithm
x	Point of evaluation

Returns: Li(n,x)

◆ Li1()

template<typename numtype >

numtype LiSK::LiSK< numtype >::Li1 ( const numtype x )

Li(n,x)

Note: Classical polylogarithm of weight n at point x. Public wrapper for the actual private implementation. A small imaginary part is assigned, i.e. x->x+iep. For the n<=4 the abbreviations Lin(x)=Li(n,x) are supported.

Parameters

n	Weight of classical polylogarithm
x	Point of evaluation

Returns: Li(n,x)

◆ Li2()

template<typename numtype >

numtype LiSK::LiSK< numtype >::Li2 ( const numtype x )

Li(n,x)

Note: Classical polylogarithm of weight n at point x. Public wrapper for the actual private implementation. A small imaginary part is assigned, i.e. x->x+iep. For the n<=4 the abbreviations Lin(x)=Li(n,x) are supported.

Parameters

n	Weight of classical polylogarithm
x	Point of evaluation

Returns: Li(n,x)

◆ Li22()

template<typename numtype >

numtype LiSK::LiSK< numtype >::Li22	(	const numtype	x,
		const numtype	y
	)

Li22(x,y)

Note: Public wrapper for Li22(x,y). A small imaginary part is assigned to x and y, i.e. x->x+iep and y->y+iep.

Parameters

x	Point of evaluation
y	Point of evaluation

Returns: Li22(x,y)

◆ Li3()

template<typename numtype >

numtype LiSK::LiSK< numtype >::Li3 ( const numtype x )

Li(n,x)

Note: Classical polylogarithm of weight n at point x. Public wrapper for the actual private implementation. A small imaginary part is assigned, i.e. x->x+iep. For the n<=4 the abbreviations Lin(x)=Li(n,x) are supported.

Parameters

n	Weight of classical polylogarithm
x	Point of evaluation

Returns: Li(n,x)

◆ Li4()

template<typename numtype >

numtype LiSK::LiSK< numtype >::Li4 ( const numtype x )

Li(n,x)

Note: Classical polylogarithm of weight n at point x. Public wrapper for the actual private implementation. A small imaginary part is assigned, i.e. x->x+iep. For the n<=4 the abbreviations Lin(x)=Li(n,x) are supported.

Parameters

n	Weight of classical polylogarithm
x	Point of evaluation

Returns: Li(n,x)

◆ Pow()

template<typename numtype >

numtype LiSK::LiSK< numtype >::Pow	(	const numtype &	x,
		const int	n
	)		const

private

Power function.

Note: Power function for exponents of integer type. Nothing more is needed here.

Parameters

x	Basis
n	Exponent

Returns: x^n

◆ Re() [1/2]

template<typename numtype >

cln::cl_R LiSK::LiSK< numtype >::Re ( const cln::cl_N & x ) const

inlineprivate

Real part.

Parameters

x	Complex number

Returns: Re(x)

◆ Re() [2/2]

template<typename numtype >

double LiSK::LiSK< numtype >::Re ( const std::complex< double > & x ) const

inlineprivate

Real part.

Parameters

x	Complex number

Returns: Re(x)

Member Data Documentation

◆ _cln_tofloat

template<typename numtype >

const bool LiSK::LiSK< numtype >::_cln_tofloat = false

private

Enable/disable floating point conversion of constants.

Note: If this flag is set true all constants in the look-up tables are given by their floating point approximation, respecting the required precision. However, problems can occur when using real input variables. Be careful! (default = false)

◆ _constants

template<typename numtype >

constants<numtype> LiSK::LiSK< numtype >::_constants

private

◆ _constants_clR

template<typename numtype >

constants<cln::cl_R> LiSK::LiSK< numtype >::_constants_clR

private

◆ _iep_clN

template<typename numtype >

const cln::cl_N LiSK::LiSK< numtype >::_iep_clN

private

Small positive imaginary part.

Note: Small positive imaginary part which will be assigned as x->x-iep. For the double precision implementation we set _iep_d= i*10^(offset-17) and in the arbitrary precision case as _iep_clN = i*10^(offset-prec), with prec set in constructor. The offset can be variied, but the user has to know what he's doing (default = 2).

◆ _iep_d

template<typename numtype >

const cp_d LiSK::LiSK< numtype >::_iep_d

private

Small positive imaginary part.

Note: Small positive imaginary part which will be assigned as x->x-iep. For the double precision implementation we set _iep_d= i*10^(offset-17) and in the arbitrary precision case as _iep_clN = i*10^(offset-prec), with prec set in constructor. The offset can be variied, but the user has to know what he's doing (default = 2).

◆ _offset

template<typename numtype >

const int LiSK::LiSK< numtype >::_offset = 2

private

Small positive imaginary part.

Note: Small positive imaginary part which will be assigned as x->x-iep. For the double precision implementation we set _iep_d= i*10^(offset-17) and in the arbitrary precision case as _iep_clN = i*10^(offset-prec), with prec set in constructor. The offset can be variied, but the user has to know what he's doing (default = 2).

◆ _prec

template<typename numtype >

const size_t LiSK::LiSK< numtype >::_prec

private

Precision value.

Note: Only relevant in arbitrary precision case. Minimum is double precision with _prec=17

◆ _step

template<typename numtype >

const unsigned LiSK::LiSK< numtype >::_step = 5

private

Step size.

Note: Set step size used during computation of constants in case an extension is required.

◆ _user_max_values

template<typename numtype >

const std::unordered_map<std::string, size_t> LiSK::LiSK< numtype >::_user_max_values

private

Initial value:

{
                        {"nHarmNum",3},                 
                        {"nPosZeta",4},                 
                        {"nNegZeta",100},               
                        {"nFactorials",100},    
                        {"nBernNum",100},               
                        {"nLiCij",200},                 
                        {"nLiBn_eq59",100}              
                }

User defined upper limits for various constants.

Note: The limits, which determine how many constants are pre-calculated can be set here. The keys should not be changed. Note: A minimum will be assumed during construction and the user choice may be overwritten. But higher values will be respected.

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

include/algorithm/LiSK/lisk.hpp

Classes

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

template<typename numtype> class LiSK::LiSK< numtype >

Constructor & Destructor Documentation

◆ LiSK()

Member Function Documentation

◆ _add_iep()

◆ _adjustDigits()

◆ _BernNum_extend()

◆ _ErrorEstimate()

◆ _Factorials_extend()

◆ _HarmNum_extend()

◆ _init()

◆ _Li1()

◆ _Li2()

◆ _Li22()

◆ _Li22_inversion()

◆ _Li22_orig()

◆ _Li22_stuffle()

◆ _Li3()

◆ _Li4()

◆ _Li_sumBn()

◆ _LiBn_eq59_extend()

◆ _LiCij_extend()

◆ _Lin_1mexpal()

◆ _Lin_basis()

◆ _Lin_expal()

◆ _Lin_inverse()

◆ _NegZeta_extend()

◆ _PosZeta_extend()

◆ _vec_max()

◆ convert()

◆ is_zero()

◆ Li()

◆ Li1()

◆ Li2()

◆ Li22()

◆ Li3()

◆ Li4()

◆ Pow()

◆ Re() [1/2]

◆ Re() [2/2]

Member Data Documentation

◆ _cln_tofloat

◆ _constants

◆ _constants_clR

◆ _iep_clN

◆ _iep_d

◆ _offset

◆ _prec

◆ _step

◆ _user_max_values

template<typename numtype>
class LiSK::LiSK< numtype >