/ 
Math-Numerical-0.05
River stage zero No dependents
/ Math::Numerical

NAME

Math::Numerical

SYNOPSIS

Numerical analysis and scientific computing related functions.

use Math::Numerical ':all';

sub f { cos($_[0]) * $_[0] ** 2 }  # cos(x)·x²

my $root = find_root(\&f, -1, 1);

DESCRIPTION

This module offers functions to manipulate numerical functions such as root finding (solver), derivatives, etc. Most of the functions of this module can receive a $func argument. This argument should always be a code reference (an anonymous sub or a reference to a named code block). And that referenced function should expect a single scalar (numeric) argument and return a single scalar (numeric) value. For efficiency reason, it is recommended to not name the argument of that function (see the example above).

CONFIGURATION

For now, this module has no global configuration available. All configuration must be directly passed to the individual functions.

FUNCTIONS

By default, none of the functions below are exported by this package. They can be selectively imported or you can import them all with the tag :all.

find_root

find_root($func, $x1, $x2, %params)

Given a function $func assumed to be continuous and a starting interval [$x1, $x2], tries to find a root of the function (a point where the function’s value is 0). The root found may be either inside or outside the starting interval.

If the function is successful it returns the root found in scalar context or, in list context, a list with the root and the value of the function at that point (which may not be exactly 0). Some options can control the precision of the returned root. Note that, for discontinuous or pathological functions, the returned value may not be a root at all.

The current implementation of this function is based on the Brent method described in the Numerical Recipes Third Edition book, section 9.3.

The function supports the following parameters:

max_iterations

How many iterations of our algorithm will be applied at most while trying to find a root for the given function. This gives an order of magnitude of the number of times that $func will be evaluated. Defaults to 100.

do_bracket

Whether the bracket function should be used to bracket a root of the function before finding the root. If this is set to a false value, then the passed $x1 and $x2 values must already form a bracket (that is, the function must take values of opposite sign at these two points). Note that, when they do, the bracket function will immediately return these values. So, if find_root return a result with do_bracket set to a false value, it will return the same result when do_bracket is set to a true value. However, if do_bracket is set to a false value, then find_root will immediately croak if the starting interval does not form a bracket of a root of the function.

When set to a true value, the bracket function is called with the same arguments as those given to find_root, so any parameter supported by bracket can also be passed to find_root.

Defaults to 1.

tolerance

The tolerance of the root found on the x-axis. That is, the returned value or, in list context, the first returned value will not be further away from the actual root than this value.

Defaults to 0.00001.

In addition, as noted above, when do_bracket is true, any of the parameters supported by the bracket function can be passed and they will be forwarded to that function.

solve

solve($func, $x1, $x2, %params)

This is an exact synonym of find_root($func, $x1, $x2, %params) in case you prefer another name. See the documentation of the find_root function for all the details.

bracket

bracket($func, $x1, $x2, %params)

Given a function $func assumed to be continuous and a starting interval [$x1, $x2], tries to find a pair of point ($a, $b) such that the function has a root somewhere between these two points (the root is bracketed by these points). The found points will be either inside or outside the starting interval.

If the function is successful, it returns a list of four elements with the values $a and $b and then the values of function at these two points. Otherwise it returns an empty list.

If $x2 is omitted or equal to $x1 then a value slightly larger than $x1 will be used. Note that if it is omitted then %params cannot be specified.

The current implementation is a mix of the inward and outward bracketing approaches exposed in the Numerical Recipes Third Edition book, section 9.1.

The function supports the following parameters:

max_iterations

How many iterations of our algorithm will be applied at most while trying to bracket the given function. This gives an order of magnitude of the number of times that $func will be evaluated. Defaults to 100.

do_outward

Whether the function will try to bracket a root in an interval larger than the one given by [$x1, $x2]. Defaults to 1.

do_inward

Whether the function will try to bracket a root in an interval smaller than the one given by [$x1, $x2]. Defaults to 1.

One of do_inward or do_outward at least must be a true value.

inward_split

Tuning parameter describing the starting number of intervals into which the starting interval is split when looking inward for a bracket. Defaults to 3.

Note that the algorithm may change and this parameter may stop working or may take a different meaning in the future.

inward_factor

Tuning parameter describing a factor by which the inwards interval are split at each iteration. Defaults to 3.

Note that the algorithm may change and this parameter may stop working or may take a different meaning in the future.

outward_factor

Tuning parameter describing how much the starting interval is grown at each iteration when looking outward for a bracket. Defaults to 1.6.

Note that the algorithm may change and this parameter may stop working or may take a different meaning in the future.

AUTHOR

Mathias Kende

COPYRIGHT AND LICENSE

Copyright 2022 Mathias Kende

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

SEE ALSO

Numerical Recipes Third Edition