numericalFunctions Package

specialFunctions Module

Legendre Module

pointwiseXY_C Module

A module that contains the class pointwiseXY_C.

numericalFunctions.lib.pointwiseXY_C.basicGaussian(accuracy)

Returns a new pointwiseXY_C instance constructed from the following equation

exp( ( x^2 / 2 )
Arguments are:
accuracy the accuracy of linear interpolation.
numericalFunctions.lib.pointwiseXY_C.createFromFunction(xs, f, parameters, accuracy, biSectionMax, checkForRoots = False, infill = True, saveDivide = True)

Returns a pointwiseXY_C instance which represents the function f(x) where f is the second argument and must be a function reference. The function f must take two arguments. The first arugment to f is x and the second is the third argument to createFromFunction. The function f must return, as a float, the y-value at x. The returned pointwiseXY_C instance may contain more points then xs (the first argument) as createFromFunction does infilling. That is, points are added recursively between the points in xs until accuracy or biSectionMax is reached.

Arguments are: ([o] implies optional argument)

xs An ascending list of x-values to use as an initial guess for the refinement of the returned pointwiseXY_C instance. f A function that returns the y-value given an x-value. parameters Any python object which may be needed by f. Passed as the second argument to f. accuracy The accuracy for infilling. biSectionMax The maximum number of bi-sections for infilling. checkForRoots [o] If true, and biSectionMax > 0, an additional point is added whenever two consecutive points cross the y-axis

at (or close to) the root (i.e., the y crossing point) (default is False).

infill [o] Infill value used for the returned pointwiseXY_C instance (default is True). safeDivide [o] SafeDivide value used for the returned pointwiseXY_C instance (default is True).

Example: Return a pointwise representation of ‘x * sin( x**2 )’ in the domain [1, 10].

import math import pointwiseXY_C def f( x, args ) :

return( x * math.sin( x * x ) )

xSin_xx = pointwiseXY_C.createFromFunction( ( 1, 10 ), f, None, 1e-3, 12 )

# A better solution may be to input the known zeros of f and force them to be 0., as

xs = [ 1 ] + [ math.sqrt( i * math.pi ) for i in xrange( 1, int( math.sqrt( 100 / math.pi ) ) ) ] + [ 10 ] xSin_xx = pointwiseXY_C.createFromFunction( xs, f, None, 1e-3, 12, checkForRoots = True )

numericalFunctions.lib.pointwiseXY_C.createFromString(str, accuracy, biSectionMax, interpolation = 'lin-lin', infill = True, safeDivide = True)

Returns a tuple of two elements. The first element is a pointwiseXY_C instance representing the float values translated from ‘str’. The second element is the portion of ‘str’ not translated

Arguments are: ([o] implies optional argument)
str The containing a list of floats to be converted. accuracy The accuracy for infilling. biSectionMax The maximum number of bi-sections for infilling. interpolation [o] the interpolation string (default is ‘lin-lin’). infill [o] Infill value used for the returned pointwiseXY_C instance (default is True). safeDivide [o] SafeDivide value used for the returned pointwiseXY_C instance (default is True).
numericalFunctions.lib.pointwiseXY_C.defaultAccuracy()

Returns the value of the default accuracy for the __init_ method.

numericalFunctions.lib.pointwiseXY_C.floatToShortestString()
floatToShortestString( value, significantDigits = 15, trimZeros = True, keepPeriod = False,
favorEFormBy = 0, includeSign = False )

Returns the float converted to either the E-form (i.e., ‘%e’) and F-form (i.e., ‘%f’) with significantDigits. The form with the shortest string representation of the float value is returned.

Arguments are:

value the float value to convert to a string, significantDigits The number of significant digits desired. Restricted to the range 0 to 24 inclusive, trimZeros If True, unneeded zeros to the right of ‘.’ are removed, keepPeriod If False, ‘.’ is removed if there is no digit to its right, favorEFormBy The integer subtracted from the length of the E-form before the form

with the shortest representation is determined,
includeSign If True, the returned string will always start with a sign character
(i.e., ‘+’ or ‘-‘). Otherwise, only negative values will have a sign.
numericalFunctions.lib.pointwiseXY_C.gaussian(accuracy, domainMin, domainMax, offset = 0., sigma = 1., amplitude = 1., dullEps = False)

Returns a new pointwiseXY_C instance constructed from the following equation

amplitude * exp( ( ( x - offset ) / sigma )^2 / 2 ) for domainMin <= x <= domainMax
Arguments are: ([o] implies optional argument)
accuracy the accuracy of linear interpolation, domainMin the lower x point generated, domainMax the upper x point generated, offset [o] the x offset of the center of the Gaussian, sigma [o] width of the Gaussian, amplitude [o] the Gaussian’s amplitude, dullEps [o] currently not used.
numericalFunctions.lib.pointwiseXY_C.interpolatePoint(interpolation, x, x1, y1, x2, y2)

Returns interpolation of x for x1 <= x <= x2 given x1, y1, x2, y2 and interpolation law. Arguments are:

interpolation a string representing the interpolation law (e.g., ‘log-lin’; see constructor’s docstring), x x point of interpolated y-value, x1 lower x-value, y1 y(x1), x2 upper x-value, y2 y(x2).
numericalFunctions.lib.pointwiseXY_C.unitbaseInterpolate(x, lw, lXY, uw, uXY)

Returns the unitbase interpolation of two XYs objects at w where the axes are labeled (w, x, y).

Arguments are:
w the point between lw and uw to return the unitbase interpolation of lXY and uXY, lw the w point where lXY resides, lXY a pointwiseXY_C instance for a function y(x), uw the w point where uXY resides, uXY a pointwiseXY_C instance for a function y(x),

scaleRange if True range values are scaled, otherwise they are unchanged.

pointwiseXY_C.pointwiseXY_C Class

class numericalFunctions.lib.pointwiseXY_C.pointwiseXY_C

Bases: object

The pointwiseXY_C class stores and manipulates a list of XY points (i.e., [x, y] pairs). Methods to add, substract, multiply and divide a pointwiseXY_C object with a scaler (i.e., a number) or other pointwiseXY_C object are provided.

Constructor: pointwiseXY_C( data = [], dataForm = ‘xys’, initialSize = 100, overflowSize = 10, accuracy = defaultAccuracy( ), biSectionMax = 3., interpolation = ‘lin-lin’, infill = True, safeDivide = False, userFlag = 0 )

Constructor arguments are ([o] implies optional argument):

data [o] the [x_i, y_i] pairs given as described by the dataForm argument, dataForm [o] can be one of three strings (case is ignored) that describes the form of data:

‘XYs’ data are a sequence of [x_i, y_i] pairs with x_i ascending (i.e., x_i < x_{i+1})
(e.g., data = [ [ 1, 1 ], [ 2.3, 2 ], [ 3.4, 6 ], [ 5.1, 4.3 ] ])
‘XsAndYs’ data are given as [xs, ys] where xs the list of x-values and ys the matching list of y-values,
(e.g., data = [ [ 1, 2.3, 3.4, 5.1 ], [ 1, 2, 6, 4.3 ] ]),
‘list’ data are given as [x_0, y_0, x_1, y_1, …, x_n, y_n],
(e.g., data = [ 1, 1, 2.3, 2, 3.4, 6, 5.1, 4.3 ]),

initialSize [o] the initial size of the primary data cache (default = 100), overflowSize [o] the initial size of the secondary (overflow) data cache (default = 10), accuracy [o] the accuracy of the data for the given interpolation (default is value returned by function defaultAccuracy) biSectionMax [o] at times (e.g., multiplication), points may need to be added to maintain the give accuracy. In this case, a region

is continuously divided into two until the accuracy is met or biSectionMax divisions have occurred (default = 3),
interpolation [o] can be one of the following strings:
‘flat’ for the domain [x_i,x_{i+1}), the y-value is y_i ‘lin-lin’ ‘lin-log’ ‘log-lin’ ‘log-log’ ‘other’

infill [o] if True, multiplication will continuously divide a region until accuracy or biSectionMax is met (default = True), safeDivide [o] if True, safe division is used (default = False) userFlag [o] an integer (of type C int) used to store a user defined flag. (see getUserFlag and setUserFlag).

allocatedSize()

Returns the size of memory allocated in the points region.

applyFunction()

Returns a new instance which is y(x) = f(y_s(x)) where f is a function of one variable and y_s(x) is self’s. y-value at x. The function f must take two arguments. The first is y_s(x) and the second (not including self) is the second argument to applyFunction. The returned object may contain more points then self as applyFunction does infilling. That is, points are added recursively between points until accuracy or biSectionMax is reached.

Arguments are:

f a function that returns the new y(x) given the old y(x), parameters any python object. Passed as the second argument to f, accuracy [o] The accuracy for infilling. If not present, taken from self, biSectionMax [o] The maximum number of bi-sections for infilling. If not present, taken from self. checkForRoots [o] If true, and biSectionMax > 0, an addition point is added whenever two consecutive points cross the y-axis

at (or close to) the root (i.e., the y crossing point).

To return f(x), set self’s y-values to x (i.e., y(x) = x for self).

areDomainsMutual()

This routine returns True if self and the first argument have a mutual domain, and false otherwise.

changeInterpolation()

Returns a new instance that is equivalent to self, but with the interpolation changed to interpolation.

Arguments are: ([o] implies optional argument)
interpolation [o] the new interpolation (default is ‘lin-lin’), accuracy [o] the accuracy of the conversion from the old to the new interpolation (default is self’s accuracy), lowerEps [o] for flat to linear, the lower eps, upperEps [o] the flat to linear, the upper eps. lowerEps and upperEps cannot both be 0.
changeInterpolationIfNeeded()

Returns self if it is one of the allowed interpolations. Otherwise, a new instance is returned that is equivalent to self, but with the interpolation changed to the interpolation of the first allowed interpolations.

Arguments are: ([o] implies optional argument)
allowedInterpolations the list of allowed interpolations, accuracy [o] the accuracy of the conversion from the old to the new interpolation (default is self’s accuracy), lowerEps [o] for flat to linear, the lower eps, upperEps [o] the flat to linear, the upper eps. lowerEps and upperEps cannot both be 0.
clip()

Returns a new instance which is the same as self, but with the y-values clipped between rangeMin and rangeMax clip may add points, to insure that the return instance has the same shape as self between rangeMin and rangeMax

Arguments are: ([o] implies optional argument)
rangeMin [o] the lower y-value for clipping, rangeMax [o] the upper y-value for clipping.
cloneToInterpolation()

A clone of self is returned with its interpolation changed, but no points altered or added. Arguments are:

interpolation the interpolation for the cloned instance.
coalescePoints()

Moves all points in overflow region to points region.

convolute()

Returns a new instance which is the convolution of self with the first argument, that must also be a pointwiseXY_C instance.

copy()

Returns a copy of self.

copyDataToXYs()

Returns a python list of self’s data as [ x1, y1 ], … [ xn, yn ] ].

Arguments are:
xScale [o] a float to scale all x-values by, yScale [o] a float to scale all y-values by.
copyDataToXsAndYs()

Returns python list of length two. The first element is a python list of self’s x-values and the second element is a python list of self’s y-values.

Arguments are:
xScale [o] a float to scale all x-values by, yScale [o] a float to scale all y-values by.
domain()

Returns the x-value of the first and last points as a tuple.

domainGrid()

Returns a list of x-values for self.

domainMax()

Returns the x-value of the last point.

domainMin()

Returns the x-value of the first point.

domainSlice()

Returns a new instance with self sliced between domainMin and domainMax.

Arguments are: ([o] implies optional argument)

domainMin [o] the lower x-value of the slice, default is domainMin of self, domainMax [o] the upper x-value of the slice, default is domainMax of self, fill [o] if True, points are added at domainMin and domainMax if they are not in self,

else only existing points in the range [domainMin, domainMax] are included.

dullEps [o] (Currently not implemented) the lower and upper points are dulled, default is 0.

dullEdges()

Returns a new instance that is a copy of self, except the endpoints are guaranteed to have 0’s for y-values as long as lowerEps and/or upperEps are none zero (see below). The following algorithm is used.

If lowerEps is zero or the y-value at domainMin is 0, then nothing is added at the lower end. Otherwise, the following is done at the lower end.

If lowerEps is positive, a point ‘abs( domainMin * lowerEps )’ above domainMin is added with its interpolated y-value; provided,
this x value is ‘abs( domainMin * lowerEps )’ less than the next x-value. In the prior sentence, if domainMin is 0, then replace ‘abs( domainMin * lowerEps )’ with ‘abs( lowerEps )’. Independent of whether a point is added, domainMin’s y-value is set to 0.
If lowerEps is negative, the logic for adding the point above domainMin for positive lowerEps is followed. In addition, a
point is added ‘abs( domainMin * lowerEps )’ below domainMin with a value of zero and the point at domainMin is reset by interpolating the new surrounding values. However, if positiveXOnly is True and the point below domainMin would cause a negative x-value (and domainMin is not negative) then the logic for positive lowerEps is implemented instead.
The logic for upperEps is similar to lowerEps except, replace domainMin with domainMax, below with above and above with below.
Also positiveXOnly is ignored.
Arguments are:
lowerEps [o] a point (or two if lowerEps is negative) is (are) added a distance domainMin * lowerEps from domainMin, upperEps [o] a point (or two if upperEps is negative) is (are) added a distance domainMax * upperEps from domainMax, positiveXOnly [o] this only applies to lowerEps and only if an added point would be negative when domainMin is non-negative.
evaluate()

Gets the y value at x.

exp(a)

Returns a new instance with ts y-values set to exp( a * [self’s y-values] ). x-values are added to meet required accuaracy.

getAccuracy()

Returns self’s accuracy value.

getBiSectionMax()

Returns self’s biSectionMax value.

getInfill()

Returns self’s infill flag.

getInterpolation()

Returns self’s interpolation as a string.

getNFStatus()

Returns self’s numerical functions status flag (an integer).

getSafeDivide()

Returns self’s safeDivide flag.

getSecondaryCacheSize()

Returns the size of self’s secondary cache.

getUserFlag()

Gets the user flag.

groupOneFunction()

Returns a python list of float values. Each value is the integral of self between two consecutive group boundaries.

Arguments are:

groupBoundaries the list of group boundaries, norm each value returned can be normalized as directed by one of the following allowed values

None no normalization is applied, ‘dx’ each value is normalized by the width of its interval, list a list of floats, one each for each group which the group is normalized by.
groupThreeFunctions()

Returns a python list of float values. Each value is the integral of the product of self, f2 and f3 between two consecutive group boundaries.

Arguments are:

f2 the second pointwiseXY_C function with the integrand being the product of self * f2 * f3 f3 the third pointwiseXY_C function with the integrand being the product of self * f2 * f3 groupBoundaries the list of group boundaries, norm each value returned can be normalized as directed by one of the following allowed values

None no normalization is applied, ‘dx’ each value is normalized by the width of its interval, list a list of floats, one each for each group which the group is normalized by.
groupTwoFunctions()

Returns a python list of float values. Each value is the integral of the product of self and f2 between two consecutive group boundaries.

Arguments are:

f2 the second pointwiseXY_C function with the integrand being the product of self * f2 groupBoundaries the list of group boundaries, norm each value returned can be normalized as directed by one of the following allowed values

None no normalization is applied, ‘dx’ each value is normalized by the width of its interval, list a list of floats, one each for each group which the group is normalized by.
integrate()

Returns float a value that is the integral of self from domainMin to domainMax.

Arguments are: ([o] implies optional argument)
domainMin [o] the lower limit of the integral, default is domainMin of self, domainMax [o] the upper limit of the integral, default is domainMax of self.
integrateWithFunction()

Returns a float value that is the integral of self times f(x) for x from domainMin to domainMax (i.e. integral dx self(x) * f(x)). This method uses an adaptive method with a Gauss-Legendre quadrature to calculate the integral to tolerance. The first argument, func, must return the value of f(x) at x. func is called as func( x, parameters ) where parameters is the third argument to this method. The Gauss-Legendre quadrature is exact for any polynomial of degree n for which n < degree where degree is one of the arguments. If recursionLimit is needed by the adaptive method, tolerance will, most likely, not be met.

Arguments are: ([o] implies optional argument)
func a python function taking x and parameters as arguments and returning the value f(x), tolerance the desired tolerance for the integral, parameters [o] a python object passed passed to func [defalut=None], domainMin [o] the lower limit of the integral [default is domainMin of self], domainMax [o] the upper limit of the integral [default is domainMax of self], degree [o] the polynomial degree for which the Gauss-Legendre quadrature is exact [default=4], recursionLimit [o] the maximum recursion depth used in the adaptive quadrature [default=10].
integrateWithWeight_sqrt_x()

Returns float a value that is the integral of self weighted by sqrt( x ) from domainMin to domainMax (i.e. integral dx sqrt( x ) * self(x)).

Arguments are: ([o] implies optional argument)
domainMin [o] the lower limit of the integral, default is domainMin of self, domainMax [o] the upper limit of the integral, default is domainMax of self.
integrateWithWeight_x()

Returns float a value that is the integral of self weighted by x from domainMin to domainMax (i.e. integral dx x * self(x)).

Arguments are: ([o] implies optional argument)
domainMin [o] the lower limit of the integral, default is domainMin of self, domainMax [o] the upper limit of the integral, default is domainMax of self.
inverse()

Returns a new instance with the x- and y-values of self being the y- and x-values of the returned instance, respectively.

isInterpolationLinear()

Returns True if self’s interpolation is ‘lin-lin’, otherwise returns False.

isInterpolationOther()

Returns True if self’s interpolation is ‘other’, otherwise returns False.

lowerIndexBoundingX()

Returns the lower index in self that bounds the x-value. -1 is returned if x is outside domain.

Arguments are:
x the x-value whose lower bounding index is return.
mergeClosePoints()

Returns a new pointwiseXY_C object whose x values are the union of self and other.

mutualify()

Returns a python list containing two pointwiseXY_C instances that are the mutualification of self and other. Mutualification is the act of modifying, if needed, two pointwiseXY_C instances so that their domains are mutual. Self and other are not altered.

Arguments are:
lowerEps1 the lowerEps applied to self if needed, see dullEdges for meaning, upperEps1 the upperEps applied to self if needed, see dullEdges for meaning, positiveXOnly1 the positiveXOnly applied to self if needed, see dullEdges for meaning, other the second pointwiseXY_C instance to mutualify self with, lowerEps2 the lowerEps applied to other if needed, see dullEdges for meaning, upperEps2 the upperEps applied to other if needed, see dullEdges for meaning, positiveXOnly2 the positiveXOnly applied to other if needed, see dullEdges for meaning,
normalize()

Returns a new instance with the same x-values as self but with the y-values scaled so that the area of the curve is 1.

Arguments are: ([o] implies optional argument)
insitu [o] If True, self is normalize and returned. Otherwise, a new instances is created and normalize and self is unchanged.
overflowAllocatedSize()

Returns the size of memory allocated for the overflow region.

overflowLength()

Returns of number of points in the overflow region.

plot()

Calls Gnuplot, if it exists, to plot self. This is a simple method, mainly for debugging.

Arguments: None.

pop()

Removes and returns point at index (default last).

range()

Returns the minimum and maximum y-values in self or 0 if self is empty.

rangeMax()

Returns the maximum y-value in self or 0 if self is empty.

rangeMin()

Returns the minimum y-value in self or 0 if self is empty.

reallocateOverflowPoints(size)

Adjusts the memory allocated for the overflow points to size (the first and only argument).

reallocatePoints(size, forceSmaller = True)

Adjusts the memory allocated for primary points to the maximum of size and the current length of self.

Arguments are: ([o] implies optional argument)
size the desired allocated size of self (actual size will be larger if length is greater than size), forceSmaller [o] if False action is only taken if allocated is significantly greater than size (default is True).
runningIntegral()

Returns, as a python list, the integrals between successive x-values.

scaleOffsetXAndY()

Returns a new pointwiseXY_C object whose x and y values are scaled and offset.

Arguments are: ([o] implies optional argument)
xScale [o] the scale for the x-axis, xOffset [o] the offset for the x-axis, yScale [o] the scale for the y-axis, yOffset [o] the offset for the y-axis, insitu [o] If True, self is scalled and offset and returned.

Otherwise, a new instances is created and returned, and self is unchanged.

setAccuracy()

Sets self’s accuracy value and returns the actual value set.

setBiSectionMax()

Sets self’s biSectionMax value and returns the actual value set.

setData()

Replaces the data in self with the frist argument. This argument must be a list. Each item of the list must contain two floats, or objects that can be convert to float (e.g., [ [ 1, 2 ], [ 2, 4 ], [ 4, 0.5 ] ]

setDataFromList()

Replaces the data in self with the python list given by the first argument.

Arguments are:
xys the list of xy-values as a single python list (e.g., [ 1, 2, 4, 3, 5, 6]
setDataFromXsAndYs()

Replaces the data in self with the 2 python lists given by the first 2 arguments.

Arguments are:
xs the list of x-values ys the list of y-values
setInfill()

Sets self’s infill flag to the first argument.

setSafeDivide()

Sets self’s safeDivide flag to the first argument.

setSecondaryCacheSize()

Sets the size of self’s secondary cache to size.

setUserFlag()

Sets the users flag via the first argument.

setValue()

Sets the y value at x.

showInteralStructure()

For debbuging only. Dumps information on internal data.

thicken()

Returns a new instance with denser points than self filled in using self’s interpolation. The number of points added are determined by the following arguments sectionSubdivideMax maximum number of points to insert between consecutive points (default 1), dDomainMax minimum dx step (default 0), fDomainMax minimum fractional step (default 1).

thin()

Returns a new instance of self thinned to accuracy (i.e., points are removed if possible).

Arguments are:
accuracy The accuracy to maintain for the function when thinning.
thinDomain()

Returns a new instance of self with fractional x-spacing between points of at least epsilon. Points are removed if needed. Fractional x-spacing is defined as

( x_{i+1} - x_i ) / ( fabs( x_{i+1} ) - fabs( x_i ) ).
Arguments are:
epsilon The fraction minimum distance between sequential x-value.
toString()

Returns a string representation of self. This method has three keyword parameters: pairsPerLine, format and pairSeparator which are defined as,

pairsPerLine the number of pairs to put on each line format a valid format to convert an (x,y) pair (i.e., two floats) into a string (e.g. format = ‘ %.3f %12.5e’) pairSeparator a string to put between every pair (e.g, to put a comma to separate pairs use pairSeparator = ‘,’)
trim()

Returns a new instance with excessive 0. y-value points at beginning and end of self removed.

union()

Returns a new pointwiseXY_C object whose x values are the union of self and other.

ysMappedToXs()

Returns the tuple (offset, y-values) where y-values is self’s y-values mapped to Xs.

Arguments are: ([o] implies optional argument)
Xs [o] List of x-values to map self to.