#
# stub class definition file for docstring parsing
#
[docs]class functional:
r"""
Functionals handling
*Introduction*
A functional is a function with parameters, defined as :math:`f(p;x)`, where :math:`p` are the parameters, and :math:`x` the arguments. Methods are available to calculate the value of a function for a series of argument values for the given set of parameters, and for the automatic calculation of the derivatives with respect to the parameters.
The created functionals can be used in the fitting or in any other that needs to have generic function values or their derivatives.
A functional has a mask associated with it, to indicate if certain parameters have to be solved for. See masks for details.
Functionals are created in a variety of ways, in general by specifying the name of the functional, together with some necessary information like e.g. the order of a polynomial, or the code needed to compile your privately defined function. Parameters can be set at creation time or later.
::
- a = fs.gaussian1d() # creates a 1D Gaussian, default arguments
- b = fs.open('gaussian1') # creates the same one
- a.state() # the 'state' of the functional
[type=0, order=-1, ndim=1, npar=3, params=[1 0 1] ]
- a.type() # its type
gaussian1d
- a.ndim() # its dimension (number of arguments)
1
- a.npar() # its number of parameters
3
- b.state()
[type=0, order=-1, ndim=1, npar=3, params=[1 0 1] ]
- a.f(1); # the value at x=1
0.0625
- a.fdf([0,0.5]); # value and derivatives
[[1:2,]
1 1 0 0
0.5 0.5 1.38629 0.693147]
In some cases an *order* can be specified as well (e.g. for polynomials):
::
- a := dfs.poly(3) # creates a 3rd order polynomial
- b := dfs.functional('polyn',3) # creates the same one, but with
# original defaults
- a.state()
[type=5, order=3, ndim=1, npar=4, params=[1 1 1 1] ]
- b.state()
[type=5, order=3, ndim=1, npar=4, params=[0 0 0 0] ]
An extremely valuable aspect of the Functionals module is the ability to create a functional from a compiled string specifying an arbitrary function. For example, let us make our own polynomial :math:`1 + 2*x + 3*x^2` and evaluate it at a few abcissa locations
::
- a := dfs.compiled ('p0 + p1*x + p2*x*x', [1,2,3]) # Define
- a.f([0,10,20]) # Evaluate at x=[0,10,20]
[1 321 1241]
The functions created can also be used to specify the function to be fitted in a least squares fit (see the fitting ).
"""
[docs] def functional(self):
r"""
Create a ``functional`` tool.
"""
pass
[docs] def f(self, x=0):
r"""
Calculate the value of the functional.
.. rubric:: Parameters
- ``x ({double, doubleVec}=0)`` - real argument values
.. rubric:: Returns
``any``
.. rubric:: Examples
::
gfn = fn.gaussian1d(2, 0, 1)
#returns 0.125
gfn.f(1)
# returns array([ 1.25000000e-01, 3.05175781e-05])
gfn.f([1,2])
"""
pass
[docs] def ndim(self):
r"""
Return the number of dimensions.
"""
pass
[docs] def done(self):
r"""
Free the functional’s resources.
"""
pass
[docs] def gaussian1d(self, amplitude=1, center=0, fwhm=1):
r"""
Create a 1-dimensional Gaussian with the specified amplitude, fwhm, and center.
.. rubric:: Parameters
- ``amplitude (double=1)`` - amplitude of Gaussian
- ``center (double=0)`` - center of Gaussian
- ``fwhm (double=1)`` - FWHM of Gaussian
.. rubric:: Returns
``functional``
.. rubric:: Examples
::
# get the value and derivatives of a Gaussian with
# height=2; center at x=1; a width of 1 at x=[0,1,2]
gfn = fn.gaussian1d(2,1,1)
# returns array([ 0.125, 2. , 0.125])
vals = gfn.f([0, 1, 2])
"""
pass
[docs] def gaussian2d(self, amplitude=1, center=[-1], fwhm=[-1], pa='0'):
r"""
Create a 2-dimensional Gaussian with the specified amplitude, fwhms, and center. The created functional has method *f* to calculate the function value at a series of *x, y* values, or the value.
.. rubric:: Parameters
- ``amplitude (double=1)`` - Amplitude of Gaussian
- ``center (doubleVec=[-1])`` - Center (x,y) position. Must have exactly 2 elements.
- ``fwhm (doubleVec=[-1])`` - FWHM of the axes. Must have exactly 2 elements.
- ``pa ({string, doubleQuant}='0')`` - The angle between the positive y axis and the major axis, measured counterclockwise.
.. rubric:: Returns
``functional``
.. rubric:: Examples
::
# major axis along the y axis
g2d = fn.gaussian2d(1,[0,0],[3,2],"90deg")
# both these commands return 0.5
v = g2d([0, 1])
v = g2d([1.5, 0])
# returns array([ 0.5, 0.5])
v = g2d.f([0,1,1.5,0])
"""
pass
[docs] def polynomial(self, coefficients=[0]):
r"""
Create a 1-dimensional polynomial function with the specified coefficents.
.. rubric:: Parameters
- ``coefficients (doubleVec=[0])`` - Array of coefficients. Number of coefficients determines order of polynomial.
.. rubric:: Returns
``functional``
.. rubric:: Examples
::
# get the value and derivatives of 3 + 2*x + 4*x*x
poly = fn.powerlogpoly(3, 2, 4)
# value at 3
vals = poly.f(3)
"""
pass
[docs] def powerlogpoly(self, coefficients=[0]):
r"""
Create a 1-dimensional power log polynomial function with the specified coefficents.
.. rubric:: Parameters
- ``coefficients (doubleVec=[0])`` - Array of coefficients.
.. rubric:: Returns
``functional``
.. rubric:: Examples
::
# get the value and derivatives of 2*x**(1+ln(x))
plp = fn.powerlogpoly(2,1,1)
# value at 3
vals = plp.f(3)
"""
pass