1Func(3) User Contributed Perl Documentation Func(3)
2
6 PDL::Func - useful functions
7
9 use PDL::Func;
10 use PDL::Math;
11 # somewhat pointless way to estimate cos and sin,
13 # but is shows that you can thread if you want to
14 # (and the library lets you)
15 #
16 my $obj = PDL::Func->init( Interpolate => "Hermite" );
17 #
18 my $x = pdl( 0 .. 45 ) * 4 * 3.14159 / 180;
19 my $y = cat( sin($x), cos($x) );
20 $obj->set( x => $x, y => $y, bc => "simple" );
21 #
22 my $xi = pdl( 0.5, 1.5, 2.5 );
23 my $yi = $obj->interpolate( $xi );
24 #
25 print "sin( $xi ) equals ", $yi->slice(':,(0)'), "\n";
26 sin( [0.5 1.5 2.5] ) equals [0.87759844 0.070737667 -0.80115622]
27 #
28 print "cos( $xi ) equals ", $yi->slice(':,(1)'), "\n";
29 cos( [0.5 1.5 2.5] ) equals [ 0.4794191 0.99768655 0.59846449]
30 #
31 print sin($xi), "\n", cos($xi), "\n";
32 [0.47942554 0.99749499 0.59847214]
33 [0.87758256 0.070737202 -0.80114362]
34
36 This module aims to contain useful functions. Honest.
37
39 This module aims to provide a relatively-uniform interface to the vari‐
40 ous interpolation methods available to PDL. The idea is that a differ‐
41 ent interpolation scheme can be used just by changing an attribute of a
42 "PDL::Func" object. Some interpolation schemes (as exemplified by the
43 SLATEC library) also provide additional functionality, such as integra‐
44 tion and gradient estimation.
45 Throughout this documentation, $x and $y refer to the function to be
47 interpolated whilst $xi and $yi are the interpolated values.
48 The avaliable types, or schemes, of interpolation are listed below.
50 Also given are the valid attributes for each scheme: the flag value
51 indicates whether it can be set (s), got (g), and if it is required (r)
52 for the method to work.
53 Interpolate => Linear
55 An extravagent way of calling the linear interpolation routine
56 PDL::Primitive::interpolate.
57 The valid attributes are:
59 Attribute Flag Description
61 x sgr x positions of data
62 y sgr function values at x positions
63 err g error flag
64 Interpolate => Hermite
66 Use the piecewice cubic Hermite interpolation routines from the
67 SLATEC library. Only available if PDL::Slatec is installed.
68 The valid attributes are:
70 Attribute Flag Description
72 x sgr x positions of data
73 y sgr function values at x positions
74 bc sgr boundary conditions
75 g g estimated gradient at x positions
76 err g error flag
77 Given the initial set of points "(x,y)", an estimate of the gradi‐
79 ent is made at these points, using the given boundary conditions.
80 The gradients are stored in the "g" attribute, accessible via:
81 $gradient = $obj->get( 'g' );
83 However, as this gradient is only calculated 'at the last moment',
85 "g" will only contain data after one of "interpolate", "gradient",
86 or "integrate" is used.
87 Boundary conditions for the Hermite routines
89 If your data is monotonic, and you are not too bothered about edge
91 effects, then the default value of "bc" of "simple" is for you. Other‐
92 wise, take a look at the description of PDL::Slatec::chic and use a
93 hash reference for the "bc" attribute, with the following keys:
94 monotonic
96 0 if the interpolant is to be monotonic in each interval (so the
97 gradient will be 0 at each switch point), otherwise the gradient is
98 calculated using a 3-point difference formula at switch points. If
99 > 0 then the interpolant is forced to lie close to the data, if < 0
100 no such control is imposed. Default = 0.
101 start
103 A perl list of one or two elements. The first element defines how
104 the boundary condition for the start of the array is to be calcu‐
105 lated; it has a range of "-5 .. 5", as given for the "ic" parameter
106 of chic. The second element, only used if options 2, 1, -1, or 2
107 are chosen, contains the value of the "vc" parameter. Default = [ 0
108 ].
109 end
111 As for "start", but for the end of the data.
112 An example would be
114 $obj->set( bc => { start => [ 1, 0 ], end => [ 1, -1 ] } )
116 which sets the first derivative at the first point to 0, and at the
118 last point to -1.
119 Errors
121 The "status" method provides a simple mechanism to check if the previ‐
123 ous method was successful. If the function returns an error flag, then
124 it is stored in the "err" attribute. To find out which routine was
125 used, use the "routine" method.
126
128 PDL::Func::init
129 $obj = PDL::Func->init( Interpolate => "Hermite", x => $x, y => $y );
131 $obj = PDL::Func->init( { x => $x, y => $y } );
132 Create a PDL::Func object, which can interpolate, and possibly inte‐
134 grate and calculate gradients of a dataset.
135 If not specified, the value of Interpolate is taken to be "Linear",
137 which means the interpolation is performed by PDL::Primitive::interpo‐
138 late. A value of "Hermite" uses piecewise cubic Hermite functions,
139 which also allows the integral and gradient of the data to be esti‐
140 mated.
141 Options can either be provided directly to the method, as in the first
143 example, or within a hash reference, as shown in the second example.
144 PDL::Func::set
146 my $nset = $obj->set( x = $newx, $y => $newy );
148 my $nset = $obj->set( { x = $newx, $y => $newy } );
149 Set attributes for a PDL::Func object.
151 The return value gives the number of the supplied attributes which were
153 actually set.
154 PDL::Func::get
156 my $x = $obj->get( x );
158 my ( $x, $y ) = $obj->get( qw( x y ) );
159 Get attributes from a PDL::Func object.
161 Given a list of attribute names, return a list of their values; in
163 scalar mode return a scalar value. If the supplied list contains an
164 unknown attribute, "get" returns a value of "undef" for that attribute.
165 PDL::Func::scheme
167 my $scheme = $obj->scheme;
169 Return the type of interpolation of a PDL::Func object.
171 Returns either "Linear" or "Hermite".
173 PDL::Func::status
175 my $status = $obj->status;
177 Returns the status of a PDL::Func object.
179 This method provides a high-level indication of the success of the last
181 method called (except for "get" which is ignored). Returns 1 if every‐
182 thing is okay, 0 if there has been a serious error, and -1 if there was
183 a problem which was not serious. In the latter case,
184 "$obj->get("err")" may provide more information, depending on the par‐
185 ticular scheme in use.
186 PDL::Func::routine
188 my $name = $obj->routine;
190 Returns the name of the last routine called by a PDL::Func object.
192 This is mainly useful for decoding the value stored in the "err"
194 attribute.
195 PDL::Func::attributes
197 $obj->attributes;
199 PDL::Func->attributes;
200 Print out the flags for the attributes of a PDL::Func object.
202 Useful in case the documentation is just too opaque!
204 PDL::Func->attributes;
206 Flags Attribute
207 SGR x
208 SGR y
209 G err
210 PDL::Func::interpolate
212 my $yi = $obj->interpolate( $xi );
214 Returns the interpolated function at a given set of points (PDL::Func).
216 A status value of -1, as returned by the "status" method, means that
218 some of the $xi points lay outside the range of the data. The values
219 for these points were calculated by extrapolation (the details depend
220 on the scheme being used).
221 PDL::Func::gradient
223 my $gi = $obj->gradient( $xi );
225 my ( $yi, $gi ) = $obj->gradient( $xi );
226 Returns the derivative and, optionally, the interpolated function for
228 the "Hermite" scheme (PDL::Func).
229 PDL::Func::integrate
231 my $ans = $obj->integrate( index => pdl( 2, 5 ) );
233 my $ans = $obj->integrate( x => pdl( 2.3, 4.5 ) );
234 Integrate the function stored in the PDL::Func object, if the scheme is
236 "Hermite".
237 The integration can either be between points of the original "x" array
239 ("index"), or arbitrary x values ("x"). For both cases, a two element
240 piddle should be given, to specify the start and end points of the
241 integration.
242 index The values given refer to the indices of the points in the "x"
244 array.
245 x The array contains the actual values to integrate between.
247 If the "status" method returns a value of -1, then one or both of the
249 integration limits did not lie inside the "x" array. Caveat emptor with
250 the result in such a case.
251
253 It should be relatively easy to provide an interface to other interpo‐
254 lation routines, such as those provided by the Gnu Scientific Library
255 (GSL), or the B-spline routines in the SLATEC library.
256 In the documentation, the methods are preceeded by "PDL::Func::" to
258 avoid clashes with functions such as "set" when using the "help" or
259 "apropos" commands within perldl.
260
262 Amalgamated "PDL::Interpolate" and "PDL::Interpolate::Slatec" to form
263 "PDL::Func". Comments greatly appreciated on the current implementa‐
264 tion, as it is not too sensible.
265 Thanks to Robin Williams, Halldór Olafsson, and Vince McIntyre.
267
269 Robin is working on a new version, that improves on the current version
270 a lot. No time scale though!
271
273 Copyright (C) 2000,2001 Doug Burke (dburke@cfa.harvard.edu). All
274 rights reserved. There is no warranty. You are allowed to redistribute
275 this software / documentation as described in the file COPYING in the
276 PDL distribution.
277perl v5.8.8 2000-04-29 Func(3)