1Func(3) User Contributed Perl Documentation Func(3)
2
6 PDL::Func - interpolation, integration, & gradient estimation
7 (differentiation) of functions
8
10 use PDL::Func;
11 use PDL::Math;
12 # 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
37 This module aims to contain useful functions. Honest.
38
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 Throughout this documentation, $x and $y refer to the function to be
48 interpolated whilst $xi and $yi are the interpolated values.
49 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 Interpolate => Linear
56 An extravagent way of calling the linear interpolation routine
57 PDL::Primitive::interpolate.
58 The valid attributes are:
60 Attribute Flag Description
62 x sgr x positions of data
63 y sgr function values at x positions
64 err g error flag
65 Interpolate => Hermite
67 Use the piecewice cubic Hermite interpolation routines from the
68 SLATEC library. Only available if PDL::Slatec is installed.
69 The valid attributes are:
71 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 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 $gradient = $obj->get( 'g' );
85 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 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 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 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 end
112 As for "start", but for the end of the data.
113 An example would be
115 $obj->set( bc => { start => [ 1, 0 ], end => [ 1, -1 ] } )
117 which sets the first derivative at the first point to 0, and at the
119 last point to -1.
120 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
128 init
129 $obj = PDL::Func->init( Interpolate => "Hermite", x => $x, y => $y );
130 $obj = PDL::Func->init( { x => $x, y => $y } );
131 Create a PDL::Func object, which can interpolate, and possibly
133 integrate and calculate gradients of a dataset.
134 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 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 set
145 my $nset = $obj->set( x => $newx, y => $newy );
146 my $nset = $obj->set( { x => $newx, y => $newy } );
147 Set attributes for a PDL::Func object.
149 The return value gives the number of the supplied attributes which were
151 actually set.
152 get
154 my $x = $obj->get( x );
155 my ( $x, $y ) = $obj->get( qw( x y ) );
156 Get attributes from a PDL::Func object.
158 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 scheme
164 my $scheme = $obj->scheme;
165 Return the type of interpolation of a PDL::Func object.
167 Returns either "Linear" or "Hermite".
169 status
171 my $status = $obj->status;
172 Returns the status of a PDL::Func object.
174 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 routine
183 my $name = $obj->routine;
184 Returns the name of the last routine called by a PDL::Func object.
186 This is mainly useful for decoding the value stored in the "err"
188 attribute.
189 attributes
191 $obj->attributes;
192 PDL::Func->attributes;
193 Print out the flags for the attributes of a PDL::Func object.
195 Useful in case the documentation is just too opaque!
197 PDL::Func->attributes;
199 Flags Attribute
200 SGR x
201 SGR y
202 G err
203 interpolate
205 my $yi = $obj->interpolate( $xi );
206 Returns the interpolated function at a given set of points (PDL::Func).
208 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 gradient
215 my $gi = $obj->gradient( $xi );
216 my ( $yi, $gi ) = $obj->gradient( $xi );
217 Returns the derivative and, optionally, the interpolated function for
219 the "Hermite" scheme (PDL::Func).
220 integrate
222 my $ans = $obj->integrate( index => pdl( 2, 5 ) );
223 my $ans = $obj->integrate( x => pdl( 2.3, 4.5 ) );
224 Integrate the function stored in the PDL::Func object, if the scheme is
226 "Hermite".
227 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 index The values given refer to the indices of the points in the "x"
234 array.
235 x The array contains the actual values to integrate between.
237 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
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 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
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 Thanks to Robin Williams, Halldór Olafsson, and Vince McIntyre.
257
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.
263perl v5.36.0 2023-01-20 Func(3)