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
40 various interpolation methods available to PDL. The idea is that a
41 different interpolation scheme can be used just by changing an
42 attribute of a "PDL::Func" object. Some interpolation schemes (as
43 exemplified by the SLATEC library) also provide additional
44 functionality, such as integration 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
79 gradient is made at these points, using the given boundary
80 conditions. The gradients are stored in the "g" attribute,
81 accessible via:
82 $gradient = $obj->get( 'g' );
84 However, as this gradient is only calculated 'at the last moment',
86 "g" will only contain data after one of "interpolate", "gradient",
87 or "integrate" is used.
88 Boundary conditions for the Hermite routines
90 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.
92 Otherwise, take a look at the description of PDL::Slatec::chic and use
93 a 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
105 calculated; it has a range of "-5 .. 5", as given for the "ic"
106 parameter of chic. The second element, only used if options 2, 1,
107 -1, or 2 are chosen, contains the value of the "vc" parameter.
108 Default = [ 0 ].
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
122 previous method was successful. If the function returns an error flag,
123 then it is stored in the "err" attribute. To find out which routine
124 was used, use the "routine" method.
125
127 PDL::Func::init
128 $obj = PDL::Func->init( Interpolate => "Hermite", x => $x, y => $y );
129 $obj = PDL::Func->init( { x => $x, y => $y } );
130 Create a PDL::Func object, which can interpolate, and possibly
132 integrate and calculate gradients of a dataset.
133 If not specified, the value of Interpolate is taken to be "Linear",
135 which means the interpolation is performed by
136 PDL::Primitive::interpolate. A value of "Hermite" uses piecewise cubic
137 Hermite functions, which also allows the integral and gradient of the
138 data to be estimated.
139 Options can either be provided directly to the method, as in the first
141 example, or within a hash reference, as shown in the second example.
142 PDL::Func::set
144 my $nset = $obj->set( x => $newx, $y => $newy );
145 my $nset = $obj->set( { x => $newx, $y => $newy } );
146 Set attributes for a PDL::Func object.
148 The return value gives the number of the supplied attributes which were
150 actually set.
151 PDL::Func::get
153 my $x = $obj->get( x );
154 my ( $x, $y ) = $obj->get( qw( x y ) );
155 Get attributes from a PDL::Func object.
157 Given a list of attribute names, return a list of their values; in
159 scalar mode return a scalar value. If the supplied list contains an
160 unknown attribute, "get" returns a value of "undef" for that attribute.
161 PDL::Func::scheme
163 my $scheme = $obj->scheme;
164 Return the type of interpolation of a PDL::Func object.
166 Returns either "Linear" or "Hermite".
168 PDL::Func::status
170 my $status = $obj->status;
171 Returns the status of a PDL::Func object.
173 This method provides a high-level indication of the success of the last
175 method called (except for "get" which is ignored). Returns 1 if
176 everything is okay, 0 if there has been a serious error, and -1 if
177 there was a problem which was not serious. In the latter case,
178 "$obj->get("err")" may provide more information, depending on the
179 particular scheme in use.
180 PDL::Func::routine
182 my $name = $obj->routine;
183 Returns the name of the last routine called by a PDL::Func object.
185 This is mainly useful for decoding the value stored in the "err"
187 attribute.
188 PDL::Func::attributes
190 $obj->attributes;
191 PDL::Func->attributes;
192 Print out the flags for the attributes of a PDL::Func object.
194 Useful in case the documentation is just too opaque!
196 PDL::Func->attributes;
198 Flags Attribute
199 SGR x
200 SGR y
201 G err
202 PDL::Func::interpolate
204 my $yi = $obj->interpolate( $xi );
205 Returns the interpolated function at a given set of points (PDL::Func).
207 A status value of -1, as returned by the "status" method, means that
209 some of the $xi points lay outside the range of the data. The values
210 for these points were calculated by extrapolation (the details depend
211 on the scheme being used).
212 PDL::Func::gradient
214 my $gi = $obj->gradient( $xi );
215 my ( $yi, $gi ) = $obj->gradient( $xi );
216 Returns the derivative and, optionally, the interpolated function for
218 the "Hermite" scheme (PDL::Func).
219 PDL::Func::integrate
221 my $ans = $obj->integrate( index => pdl( 2, 5 ) );
222 my $ans = $obj->integrate( x => pdl( 2.3, 4.5 ) );
223 Integrate the function stored in the PDL::Func object, if the scheme is
225 "Hermite".
226 The integration can either be between points of the original "x" array
228 ("index"), or arbitrary x values ("x"). For both cases, a two element
229 piddle should be given, to specify the start and end points of the
230 integration.
231 index The values given refer to the indices of the points in the "x"
233 array.
234 x The array contains the actual values to integrate between.
236 If the "status" method returns a value of -1, then one or both of the
238 integration limits did not lie inside the "x" array. Caveat emptor with
239 the result in such a case.
240
242 It should be relatively easy to provide an interface to other
243 interpolation routines, such as those provided by the Gnu Scientific
244 Library (GSL), or the B-spline routines in the SLATEC library.
245 In the documentation, the methods are preceeded by "PDL::Func::" to
247 avoid clashes with functions such as "set" when using the "help" or
248 "apropos" commands within perldl.
249
251 Amalgamated "PDL::Interpolate" and "PDL::Interpolate::Slatec" to form
252 "PDL::Func". Comments greatly appreciated on the current
253 implementation, as it is not too sensible.
254 Thanks to Robin Williams, HalldA~Xr Olafsson, and Vince McIntyre.
256
258 Robin is working on a new version, that improves on the current version
259 a lot. No time scale though!
260
262 Copyright (C) 2000,2001 Doug Burke (dburke@cfa.harvard.edu). All
263 rights reserved. There is no warranty. You are allowed to redistribute
264 this software / documentation as described in the file COPYING in the
265 PDL distribution.
266perl v5.12.3 2011-03-31 Func(3)