1Func(3)               User Contributed Perl Documentation              Func(3)
2
3
4

NAME

6       PDL::Func - interpolation, integration, & gradient estimation
7       (differentiation) of functions
8

SYNOPSIS

10        use PDL::Func;
11        use PDL::Math;
12
13        # somewhat pointless way to estimate cos and sin,
14        # but is shows that you can broadcast if you want to
15        # (and the library lets you)
16        #
17        my $obj = PDL::Func->init( Interpolate => "Hermite" );
18        #
19        my $x = pdl( 0 .. 45 ) * 4 * 3.14159 / 180;
20        my $y = cat( sin($x), cos($x) );
21        $obj->set( x => $x, y => $y, bc => "simple" );
22        #
23        my $xi = pdl( 0.5, 1.5, 2.5 );
24        my $yi = $obj->interpolate( $xi );
25        #
26        print "sin( $xi ) equals ", $yi->slice(':,(0)'), "\n";
27        sin( [0.5 1.5 2.5] ) equals  [0.87759844 0.070737667 -0.80115622]
28        #
29        print "cos( $xi ) equals ", $yi->slice(':,(1)'), "\n";
30        cos( [0.5 1.5 2.5] ) equals  [ 0.4794191 0.99768655 0.59846449]
31        #
32        print sin($xi), "\n", cos($xi), "\n";
33        [0.47942554 0.99749499 0.59847214]
34        [0.87758256 0.070737202 -0.80114362]
35

DESCRIPTION

37       This module aims to contain useful functions. Honest.
38

INTERPOLATION AND MORE

40       This module aims to provide a relatively-uniform interface to the
41       various interpolation methods available to PDL.  The idea is that a
42       different interpolation scheme can be used just by changing an
43       attribute of a "PDL::Func" object.  Some interpolation schemes (as
44       exemplified by the SLATEC library) also provide additional
45       functionality, such as integration and gradient estimation.
46
47       Throughout this documentation, $x and $y refer to the function to be
48       interpolated whilst $xi and $yi are the interpolated values.
49
50       The available types, or schemes, of interpolation are listed below.
51       Also given are the valid attributes for each scheme: the flag value
52       indicates whether it can be set (s), got (g), and if it is required (r)
53       for the method to work.
54
55       Interpolate => Linear
56           An extravagent way of calling the linear interpolation routine
57           PDL::Primitive::interpolate.
58
59           The valid attributes are:
60
61            Attribute    Flag  Description
62            x            sgr   x positions of data
63            y            sgr   function values at x positions
64            err          g     error flag
65
66       Interpolate => Hermite
67           Use the piecewice cubic Hermite interpolation routines from the
68           SLATEC library.  Only available if PDL::Slatec is installed.
69
70           The valid attributes are:
71
72            Attribute    Flag  Description
73            x            sgr   x positions of data
74            y            sgr   function values at x positions
75            bc           sgr   boundary conditions
76            g            g     estimated gradient at x positions
77            err          g     error flag
78
79           Given the initial set of points "(x,y)", an estimate of the
80           gradient is made at these points, using the given boundary
81           conditions. The gradients are stored in the "g" attribute,
82           accessible via:
83
84            $gradient = $obj->get( 'g' );
85
86           However, as this gradient is only calculated 'at the last moment',
87           "g" will only contain data after one of "interpolate", "gradient",
88           or "integrate" is used.
89
90   Boundary conditions for the Hermite routines
91       If your data is monotonic, and you are not too bothered about edge
92       effects, then the default value of "bc" of "simple" is for you.
93       Otherwise, take a look at the description of PDL::Slatec::chic and use
94       a hash reference for the "bc" attribute, with the following keys:
95
96       monotonic
97          0 if the interpolant is to be monotonic in each interval (so the
98          gradient will be 0 at each switch point), otherwise the gradient is
99          calculated using a 3-point difference formula at switch points.  If
100          > 0 then the interpolant is forced to lie close to the data, if < 0
101          no such control is imposed.  Default = 0.
102
103       start
104          A perl list of one or two elements. The first element defines how
105          the boundary condition for the start of the array is to be
106          calculated; it has a range of "-5 .. 5", as given for the "ic"
107          parameter of chic.  The second element, only used if options 2, 1,
108          -1, or 2 are chosen, contains the value of the "vc" parameter.
109          Default = [ 0 ].
110
111       end
112          As for "start", but for the end of the data.
113
114       An example would be
115
116        $obj->set( bc => { start => [ 1, 0 ], end => [ 1, -1 ] } )
117
118       which sets the first derivative at the first point to 0, and at the
119       last point to -1.
120
121   Errors
122       The "status" method provides a simple mechanism to check if the
123       previous method was successful.  If the function returns an error flag,
124       then it is stored in the "err" attribute.  To find out which routine
125       was used, use the "routine" method.
126

FUNCTIONS

128   init
129        $obj = PDL::Func->init( Interpolate => "Hermite", x => $x, y => $y );
130        $obj = PDL::Func->init( { x => $x, y => $y } );
131
132       Create a PDL::Func object, which can interpolate, and possibly
133       integrate and calculate gradients of a dataset.
134
135       If not specified, the value of Interpolate is taken to be "Linear",
136       which means the interpolation is performed by
137       PDL::Primitive::interpolate.  A value of "Hermite" uses piecewise cubic
138       Hermite functions, which also allows the integral and gradient of the
139       data to be estimated.
140
141       Options can either be provided directly to the method, as in the first
142       example, or within a hash reference, as shown in the second example.
143
144   set
145        my $nset = $obj->set( x => $newx, y => $newy );
146        my $nset = $obj->set( { x => $newx, y => $newy } );
147
148       Set attributes for a PDL::Func object.
149
150       The return value gives the number of the supplied attributes which were
151       actually set.
152
153   get
154        my $x         = $obj->get( x );
155        my ( $x, $y ) = $obj->get( qw( x y ) );
156
157       Get attributes from a PDL::Func object.
158
159       Given a list of attribute names, return a list of their values; in
160       scalar mode return a scalar value.  If the supplied list contains an
161       unknown attribute, "get" returns a value of "undef" for that attribute.
162
163   scheme
164        my $scheme = $obj->scheme;
165
166       Return the type of interpolation of a PDL::Func object.
167
168       Returns either "Linear" or "Hermite".
169
170   status
171        my $status = $obj->status;
172
173       Returns the status of a PDL::Func object.
174
175       This method provides a high-level indication of the success of the last
176       method called (except for "get" which is ignored).  Returns 1 if
177       everything is okay, 0 if there has been a serious error, and -1 if
178       there was a problem which was not serious.  In the latter case,
179       "$obj->get("err")" may provide more information, depending on the
180       particular scheme in use.
181
182   routine
183        my $name = $obj->routine;
184
185       Returns the name of the last routine called by a PDL::Func object.
186
187       This is mainly useful for decoding the value stored in the "err"
188       attribute.
189
190   attributes
191        $obj->attributes;
192        PDL::Func->attributes;
193
194       Print out the flags for the attributes of a PDL::Func object.
195
196       Useful in case the documentation is just too opaque!
197
198        PDL::Func->attributes;
199        Flags  Attribute
200         SGR    x
201         SGR    y
202         G      err
203
204   interpolate
205        my $yi = $obj->interpolate( $xi );
206
207       Returns the interpolated function at a given set of points (PDL::Func).
208
209       A status value of -1, as returned by the "status" method, means that
210       some of the $xi points lay outside the range of the data. The values
211       for these points were calculated by extrapolation (the details depend
212       on the scheme being used).
213
214   gradient
215        my $gi          = $obj->gradient( $xi );
216        my ( $yi, $gi ) = $obj->gradient( $xi );
217
218       Returns the derivative and, optionally, the interpolated function for
219       the "Hermite" scheme (PDL::Func).
220
221   integrate
222        my $ans = $obj->integrate( index => pdl( 2, 5 ) );
223        my $ans = $obj->integrate( x => pdl( 2.3, 4.5 ) );
224
225       Integrate the function stored in the PDL::Func object, if the scheme is
226       "Hermite".
227
228       The integration can either be between points of the original "x" array
229       ("index"), or arbitrary x values ("x"). For both cases, a two element
230       ndarray should be given, to specify the start and end points of the
231       integration.
232
233       index  The values given refer to the indices of the points in the "x"
234              array.
235
236       x      The array contains the actual values to integrate between.
237
238       If the "status" method returns a value of -1, then one or both of the
239       integration limits did not lie inside the "x" array. Caveat emptor with
240       the result in such a case.
241

TODO

243       It should be relatively easy to provide an interface to other
244       interpolation routines, such as those provided by the Gnu Scientific
245       Library (GSL), or the B-spline routines in the SLATEC library.
246
247       In the documentation, the methods are preceded by "PDL::Func::" to
248       avoid clashes with functions such as "set" when using the "help" or
249       "apropos" commands within perldl or pdl2.
250

HISTORY

252       Amalgamated "PDL::Interpolate" and "PDL::Interpolate::Slatec" to form
253       "PDL::Func". Comments greatly appreciated on the current
254       implementation, as it is not too sensible.
255
256       Thanks to Robin Williams, Halldór Olafsson, and Vince McIntyre.
257

AUTHOR

259       Copyright (C) 2000,2001 Doug Burke (dburke@cfa.harvard.edu).  All
260       rights reserved. There is no warranty.  You are allowed to redistribute
261       this software / documentation as described in the file COPYING in the
262       PDL distribution.
263
264
265
266perl v5.34.0                      2022-02-28                           Func(3)
Impressum