Math::Utils(3pm)

1Math::Utils(3)        User Contributed Perl Documentation       Math::Utils(3)
2
3
4

NAME

6       Math::Utils - Useful mathematical functions not in Perl.
7

SYNOPSIS

9           use Math::Utils qw(:utility);    # Useful functions
10
11           #
12           # Base 10 and base 2 logarithms.
13           #
14           $scale = log10($pagewidth);
15           $bits = log2(1/$probability);
16
17           #
18           # Two uses of sign().
19           #
20           $d = sign($z - $w);
21
22           @ternaries = sign(@coefficients);
23
24           #
25           # Using copysign(), $dist will be doubled negative or
26           # positive $offest, depending upon whether ($from - $to)
27           # is positive or negative.
28           #
29           my $dist = copysign(2 * $offset, $from - $to);
30
31           #
32           # Change increment direction if goal is negative.
33           #
34           $incr = flipsign($incr, $goal);
35
36           #
37           # floor() and ceil() functions.
38           #
39           $point = floor($goal);
40           $limit = ceil($goal);
41
42           #
43           # gcd() and lcm() functions.
44           #
45           $divisor = gcd(@multipliers);
46           $numerator = lcm(@multipliers);
47
48           #
49           # Safe(r) summation.
50           #
51           $tot = fsum(@inputs);
52
53           #
54           # The remainders of n after successive divisions of b, or
55           # remainders after a set of divisions.
56           #
57           @rems = moduli($n, $b);
58
59       or
60
61           use Math::Utils qw(:compare);    # Make comparison functions with tolerance.
62
63           #
64           # Floating point comparison function.
65           #
66           my $fltcmp = generate_fltmcp(1.0e-7);
67
68           if (&$fltcmp($x0, $x1) < 0)
69           {
70               add_left($data);
71           }
72           else
73           {
74               add_right($data);
75           }
76
77           #
78           # Or we can create single-operation comparison functions.
79           #
80           # Here we are only interested in the greater than and less than
81           # comparison functions.
82           #
83           my(undef, undef,
84               $approx_gt, undef, $approx_lt) = generate_relational(1.5e-5);
85
86       or
87
88           use Math::Utils qw(:polynomial);    # Basic polynomial ops
89
90           #
91           # Coefficient lists run from 0th degree upward, left to right.
92           #
93           my @c1 = (1, 3, 5, 7, 11, 13, 17, 19);
94           my @c2 = (1, 3, 1, 7);
95           my @c3 = (1, -1, 1)
96
97           my $c_ref = pl_mult(\@c1, \@c2);
98           $c_ref = pl_add($c_ref, \@c3);
99

EXPORT

101       All functions can be exported by name, or by using the tag that they're
102       grouped under.
103
104   utility tag
105       Useful, general-purpose functions, including those that originated in
106       FORTRAN and were implemented in Perl in the module Math::Fortran, by J.
107       A. R. Williams.
108
109       There is a name change -- copysign() was known as sign() in
110       Math::Fortran.
111
112       log10()
113
114           $xlog10 = log10($x);
115           @xlog10 = log10(@x);
116
117       Return the log base ten of the argument. A list form of the function is
118       also provided.
119
120       log2()
121
122           $xlog2 = log2($x);
123           @xlog2 = log2(@x);
124
125       Return the log base two of the argument. A list form of the function is
126       also provided.
127
128       sign()
129
130           $s = sign($x);
131           @valsigns = sign(@values);
132
133       Returns -1 if the argument is negative, 0 if the argument is zero, and
134       1 if the argument is positive.
135
136       In list form it applies the same operation to each member of the list.
137
138       copysign()
139
140           $ms = copysign($m, $n);
141           $s = copysign($x);
142
143       Take the sign of the second argument and apply it to the first. Zero is
144       considered part of the positive signs.
145
146           copysign(-5, 0);  # Returns 5.
147           copysign(-5, 7);  # Returns 5.
148           copysign(-5, -7); # Returns -5.
149           copysign(5, -7);  # Returns -5.
150
151       If there is only one argument, return -1 if the argument is negative,
152       otherwise return 1. For example, copysign(1, -4) and copysign(-4) both
153       return -1.
154
155       flipsign()
156
157           $ms = flipsign($m, $n);
158
159       Multiply the signs of the arguments and apply it to the first. As with
160       copysign(), zero is considered part of the positive signs.
161
162       Effectively this means change the sign of the first argument if the
163       second argument is negative.
164
165           flipsign(-5, 0);  # Returns -5.
166           flipsign(-5, 7);  # Returns -5.
167           flipsign(-5, -7); # Returns 5.
168           flipsign(5, -7);  # Returns -5.
169
170       If for some reason flipsign() is called with a single argument, that
171       argument is returned unchanged.
172
173       floor()
174
175           $b = floor($a/2);
176
177           @ilist = floor(@numbers);
178
179       Returns the greatest integer less than or equal to its argument.  A
180       list form of the function also exists.
181
182           floor(1.5, 1.87, 1);        # Returns (1, 1, 1)
183           floor(-1.5, -1.87, -1);     # Returns (-2, -2, -1)
184
185       ceil()
186
187           $b = ceil($a/2);
188
189           @ilist = ceil(@numbers);
190
191       Returns the lowest integer greater than or equal to its argument.  A
192       list form of the function also exists.
193
194           ceil(1.5, 1.87, 1);        # Returns (2, 2, 1)
195           ceil(-1.5, -1.87, -1);     # Returns (-1, -1, -1)
196
197       fsum()
198
199       Return a sum of the values in the list, done in a manner to avoid
200       rounding and cancellation errors. Currently this is done via Kahan's
201       summation algorithm
202       <https://en.wikipedia.org/wiki/Kahan_summation_algorithm>.
203
204       gcd
205
206       hcf
207
208       Return the greatest common divisor (also known as the highest common
209       factor) of a list of integers. These are simply synomyms:
210
211           $factor = gcd(@values);
212           $factor = hfc(@numbers);
213
214       lcm
215
216       Return the least common multiple of a list of integers.
217
218           $factor = lcm(@values);
219
220       moduli()
221
222       Return the moduli of an integer after repeated divisions. The
223       remainders are returned in a list from left to right.
224
225           @digits = moduli(1899, 10);   # Returns (9, 9, 8, 1)
226           @rems = moduli(29, 3);        # Returns (2, 0, 0, 1)
227
228   compare tag
229       Create comparison functions for floating point (non-integer) numbers.
230
231       Since exact comparisons of floating point numbers tend to be iffy, the
232       comparison functions use a tolerance chosen by you. You may then use
233       those functions from then on confident that comparisons will be
234       consistent.
235
236       If you do not provide a tolerance, a default tolerance of 1.49012e-8
237       (approximately the square root of an Intel Pentium's machine epsilon
238       <https://en.wikipedia.org/wiki/Machine_epsilon>) will be used.
239
240       generate_fltcmp()
241
242       Returns a comparison function that will compare values using a
243       tolerance that you supply. The generated function will return -1 if the
244       first argument compares as less than the second, 0 if the two arguments
245       compare as equal, and 1 if the first argument compares as greater than
246       the second.
247
248           my $fltcmp = generate_fltcmp(1.5e-7);
249
250           my(@xpos) = grep {&$fltcmp($_, 0) == 1} @xvals;
251
252       generate_relational()
253
254       Returns a list of comparison functions that will compare values using a
255       tolerance that you supply. The generated functions will be the
256       equivalent of the equal, not equal, greater than, greater than or
257       equal, less than, and less than or equal operators.
258
259           my($eq, $ne, $gt, $ge, $lt, $le) = generate_relational(1.5e-7);
260
261           my(@approx_5) = grep {&$eq($_, 5)} @xvals;
262
263       Of course, if you were only interested in not equal, you could use:
264
265           my(undef, $ne) = generate_relational(1.5e-7);
266
267           my(@not_around5) = grep {&$ne($_, 5)} @xvals;
268
269   polynomial tag
270       Perform some polynomial operations on plain lists of coefficients.
271
272           #
273           # The coefficient lists are presumed to go from low order to high:
274           #
275           @coefficients = (1, 2, 4, 8);    # 1 + 2x + 4x**2 + 8x**3
276
277       In all functions the coeffcient list is passed by reference to the
278       function, and the functions that return coefficients all return
279       references to a coefficient list.
280
281       It is assumed that any leading zeros in the coefficient lists have
282       already been removed before calling these functions, and that any
283       leading zeros found in the returned lists will be handled by the
284       caller. This caveat is particularly important to note in the case of
285       "pl_div()".
286
287       Although these functions are convenient for simple polynomial
288       operations, for more advanced polynonial operations Math::Polynomial is
289       recommended.
290
291       pl_evaluate()
292
293           $y = pl_evaluate(\@coefficients, $x);
294           @yvalues = pl_evaluate(\@coefficients, \@xvalues);
295
296       You can also use lists of the X values or X array references:
297
298           @yvalues = pl_evaluate(\@coefficients, \@xvalues, \@primes, $x, @negatives);
299
300       Returns either a y-value for a corresponding x-value, or a list of
301       y-values on the polynomial for a corresponding list of x-values, using
302       Horner's method.
303
304       pl_dxevaluate()
305
306           ($y, $dy, $ddy) = pl_dxevaluate(\@coefficients, $x);
307
308       Returns p(x), p'(x), and p"(x) of the polynomial for an x-value, using
309       Horner's method. Note that unlike "pl_evaluate()" above, the function
310       can only use one x-value.
311
312       If the polynomial is a linear equation, the second derivative value
313       will be zero.  Similarly, if the polynomial is a simple constant, the
314       first derivative value will be zero.
315
316       pl_translate()
317
318           $x = [8, 3, 1];
319           $y = [3, 1];
320
321           #
322           # Translating C<x**2 + 3*x + 8> by C<x + 3> returns [26, 9, 1]
323           #
324           $z = pl_translate($x, $y);
325
326       Returns a polynomial transformed by substituting a polynomial variable
327       with another polynomial.  For example, a simple linear translation by 1
328       to the polynomial "x**3 + x**2 + 4*x + 4" would be accomplished by
329       setting x = (y - 1); resulting in "x**3 - 2*x**2 + 5*x".
330
331           $x = [4, 4, 1, 1];
332           $y = [-1, 1];
333           $z = pl_translate($x, $y);         # Becomes [0, 5, -2, 1]
334
335       pl_add()
336
337           $polyn_ref = pl_add(\@m, \@n);
338
339       Add two lists of numbers as though they were polynomial coefficients.
340
341       pl_sub()
342
343           $polyn_ref = pl_sub(\@m, \@n);
344
345       Subtract the second list of numbers from the first as though they were
346       polynomial coefficients.
347
348       pl_div()
349
350           ($q_ref, $r_ref) = pl_div(\@numerator, \@divisor);
351
352       Synthetic division for polynomials. Divides the first list of
353       coefficients by the second list.
354
355       Returns references to the quotient and the remainder.
356
357       Remember to check for leading zeros (which are rightmost in the list)
358       in the returned values. For example,
359
360           my @n = (4, 12, 9, 3);
361           my @d = (1, 3, 3, 1);
362
363           my($q_ref, $r_ref) = pl_div(\@n, \@d);
364
365       After division you will have returned "(3)" as the quotient, and "(1,
366       3, 0)" as the remainder. In general, you will want to remove the
367       leading zero, or for that matter values within epsilon of zero, in the
368       remainder.
369
370           my($q_ref, $r_ref) = pl_div($f1, $f2);
371
372           #
373           # Remove any leading zeros (i.e., numbers smaller in
374           # magnitude than machine epsilon) in the remainder.
375           #
376           my @remd = @{$r_ref};
377           pop @remd while (@remd and abs($remd[$#remd]) < $epsilon);
378
379           $f1 = $f2;
380           $f2 = [@remd];
381
382       If $f1 and $f2 were to go through that bit of code again, not removing
383       the leading zeros would lead to a divide-by-zero error.
384
385       If either list of coefficients is empty, pl_div() returns undefs for
386       both quotient and remainder.
387
388       pl_mult()
389
390           $m_ref = pl_mult(\@coefficients1, \@coefficients2);
391
392       Returns the reference to the product of the two multiplicands.
393
394       pl_derivative()
395
396           $poly_ref = pl_derivative(\@coefficients);
397
398       Returns the derivative of a polynomial.
399
400       pl_antiderivative()
401
402           $poly_ref = pl_antiderivative(\@coefficients);
403
404       Returns the antiderivative of a polynomial. The constant value is
405       always set to zero and will need to be changed by the caller if a
406       different constant is needed.
407
408         my @coefficients = (1, 2, -3, 2);
409         my $integral = pl_antiderivative(\@coefficients);
410
411         #
412         # Integral needs to be 0 at x = 1.
413         #
414         my @coeff1 = @{$integral};
415         $coeff1[0] = - pl_evaluate($integral, 1);
416

AUTHOR

418       John M. Gamble, "<jgamble at cpan.org>"
419

BUGS

439       Please report any bugs or feature requests to "bug-math-util at
440       rt.cpan.org", or through the web interface at
441       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Math-Utils>.  I will be
442       notified, and then you'll automatically be notified of progress on your
443       bug as I make changes.
444

SUPPORT

446       This module is on Github at <https://github.com/jgamble/Math-Utils>.
447
448       You can also look for information at:
449
450       ·   RT: CPAN's request tracker (report bugs here)
451
452           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Math-Utils>
453
454       ·   AnnoCPAN: Annotated CPAN documentation
455
456           <http://annocpan.org/dist/Math-Utils>
457
458       ·   CPAN Ratings
459
460           <http://cpanratings.perl.org/d/Math-Utils>
461
462       ·   Search CPAN
463
464           <http://search.cpan.org/dist/Math-Utils/>
465

ACKNOWLEDGEMENTS

467       To J. A. R. Williams who got the ball rolling with Math::Fortran.
468

LICENSE AND COPYRIGHT

470       Copyright (c) 2017 John M. Gamble. All rights reserved. This program is
471       free software; you can redistribute it and/or modify it under the same
472       terms as Perl itself.
473
474
475
476perl v5.30.1                      2020-01-30                    Math::Utils(3)