diff --git a/.travis.yml b/.travis.yml index 4d520555..07ad0648 100644 --- a/.travis.yml +++ b/.travis.yml @@ -2,6 +2,8 @@ language: julia os: - osx - linux + - windows + julia: - 1.0 - 1.1 @@ -9,13 +11,30 @@ julia: - 1.3 - 1.4 - nightly -matrix: - allow_failures: - - julia: nightly + notifications: email: false -#script: -# - if [[ -a .git/shallow ]]; then git fetch --unshallow; fi -# - julia -e 'Pkg.clone(pwd()); Pkg.build("Roots"); Pkg.test("Roots"; coverage=true)'; + +codecov: true + +jobs: + allow_failures: + - julia: nightly + include: + - stage: "Documentation" + julia: 1.4 + os: linux + env: + - GKSwstype="100" + script: + - julia --project=docs/ -e 'using Pkg; Pkg.instantiate(); Pkg.develop(PackageSpec(path=pwd()))' + - julia --project=docs/ docs/make.jl + after_success: skip + after_success: - - julia -e 'cd(Pkg.dir("Roots")); Pkg.add("Coverage"); using Coverage; Coveralls.submit(Coveralls.process_folder())'; + - | + julia -e ' + using Pkg + Pkg.add("Coverage") + using Coverage + Codecov.submit(process_folder())' diff --git a/Project.toml b/Project.toml index ff862e08..f08fc049 100644 --- a/Project.toml +++ b/Project.toml @@ -1,6 +1,6 @@ name = "Roots" uuid = "f2b01f46-fcfa-551c-844a-d8ac1e96c665" -version = "1.0.1" +version = "1.0.2" [deps] Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7" diff --git a/README.md b/README.md index 52ac76c0..a2197796 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,10 @@ +[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://juliahub.com/docs/Roots/) Linux: [![Build Status](https://travis-ci.org/JuliaMath/Roots.jl.svg?branch=master)](https://travis-ci.org/JuliaMath/Roots.jl) Windows: [![Build status](https://ci.appveyor.com/api/projects/status/goteuptn5kypafyl?svg=true)](https://ci.appveyor.com/project/jverzani/roots-jl) +https://juliahub.com/docs/Roots/ +Documentation + # Root finding functions for Julia diff --git a/doc/roots.ipynb b/doc/roots.ipynb deleted file mode 100644 index 073cba3f..00000000 --- a/doc/roots.ipynb +++ /dev/null @@ -1,167 +0,0 @@ -{ - "cells": [ - {"cell_type":"markdown","source":"

The Roots package

","metadata":{"internals":{"slide_type":"subslide","slide_helper":"subslide_end"},"slideshow":{"slide_type":"slide"},"slide_helper":"slide_end"}}, -{"cell_type":"markdown","source":"

The Roots package contains simple routines for finding zeros of continuous scalar functions of a single real variable. A zero of $f$ is a value $c$ where $f(c) = 0$. The basic interface is through the function find_zero, which through multiple dispatch can handle many different cases.

","metadata":{}}, -{"cell_type":"markdown","source":"

In the following, we will use Plots for plotting and ForwardDiff to take derivatives.

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["Plots.PyPlotBackend()"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["using Roots\nusing Plots, ForwardDiff; pyplot();"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

Bracketing

","metadata":{"internals":{"slide_type":"subslide","slide_helper":"subslide_end"},"slideshow":{"slide_type":"slide"},"slide_helper":"slide_end"}}, -{"cell_type":"markdown","source":"

For a function $f$ (univariate, real-valued) a bracket is a pair $ a < b $ for which $f(a) \\cdot f(b) < 0$. That is the function values have different signs at $a$ and $b$. If $f$ is a continuous function this ensures (Bolzano) there will be a zero in the interval $[a,b]$. If $f$ is not continuous, then there must be a point $c$ in $[a,b]$ where the function \"jumps\" over $0$.

","metadata":{}}, -{"cell_type":"markdown","source":"

Such values can be found, up to floating point roundoff. That is, given f(a) * f(b) < 0, a value c with a < c < b can be found where either f(c) == 0.0 or f(prevfloat(c)) * f(c) < 0 or f(c) * f(nextfloat(c)) < 0.

","metadata":{}}, -{"cell_type":"markdown","source":"

To illustrate, consider the function $f(x) = \\cos(x) - x$. From the graph we see readily that $[0,1]$ is a bracket (which we emphasize with an overlay):

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":"Plot(...)","image/png":"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"},"metadata":{"image/png":{"height":480,"width":600}},"execution_count":1}],"cell_type":"code","source":["f(x) = cos(x) - x\nplot(f, -2, 2)\nplot!([0,1], [0,0], linewidth=2)"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

The Roots package includes the bisection algorithm through find_zero. We use a vector or tuple to specify the initial condition and Bisection() to specify the algorithm:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["(0.7390851332151607, 0.0)"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["x = find_zero(f, (0, 1), Bisection()) # alternatively fzero(f, [0, 1])\nx, f(x)"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

For this function we see that f(x) is 0.0.

","metadata":{}}, -{"cell_type":"markdown","source":"
","metadata":{}}, -{"cell_type":"markdown","source":"

Next consider $f(x) = \\sin(x)$. A known zero is $\\pi$. Trigonometry tells us that $[\\pi/2, 3\\pi/2]$ will be a bracket. In this call Bisection() is not specified, as it will be the default when the initial value is specified as a pair of numbers:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["(3.141592653589793, 1.2246467991473532e-16)"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["f(x) = sin(x)\nx = find_zero(f, (pi/2, 3pi/2))\nx, f(x)"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

This value of x does not exactly produce a zero, however, it is as close as can be:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["true"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["f(prevfloat(x)) * f(x) < 0.0 || f(x) * f(nextfloat(x)) < 0.0"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

That is, at x the function is changing sign.

","metadata":{}}, -{"cell_type":"markdown","source":"

From a mathematical perspective, a zero is guaranteed for a continuous function. However, the computer algorithm doesn't assume continuity, it just looks for changes of sign. As such, the algorithm will identify discontinuities, not just zeros. For example:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["-0.0"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["find_zero(x -> 1/x, (-1, 1))"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

The endpoints and function values can even be infinite:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["-0.0"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["find_zero(x -> Inf*sign(x), (-Inf, Inf)) # Float64 only"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

The basic algorithm used for bracketing when the values are simple floating point values is a modification of the bisection method. For big float values, an algorithm due to Alefeld, Potra, and Shi is used.

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["3.141592653589793238462643383279502884197169399375105820974944592307816406286198"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["find_zero(sin, (big(3), big(4))) # uses a different algorithm then for (3,4)"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

By default, bisection will converge to machine tolerance. This may provide more accuracy than desired. A tolerance may be specified to terminate early, thereby utilizing fewer resources. For example, this uses 19 steps to reach accuracy to $10^{-6}$ (without specifying xatol it uses 51 steps):

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["-6.27832957178498e-7"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["rt = find_zero(sin, (3.0, 4.0), xatol=1e-6)\nrt - pi"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

Non-bracketing problems

","metadata":{"internals":{"slide_type":"subslide","slide_helper":"subslide_end"},"slideshow":{"slide_type":"slide"},"slide_helper":"slide_end"}}, -{"cell_type":"markdown","source":"

Bracketing methods have guaranteed convergence, but in general require many more function calls than are needed to produce an answer. If a good initial guess is known, then the find_zero function provides an interface to some different iterative algorithms that are more efficient. Unlike bracketing methods, these algorithms may not converge to the desired root if the initial guess is not well chosen.

","metadata":{}}, -{"cell_type":"markdown","source":"

The default algorithm is modeled after an algorithm used for HP-34 calculators. This algorithm is designed to be more forgiving of the quality of the initial guess at the cost of possibly performing many more steps than other algorithms, as if the algorithm encounters a bracket, bisection will be used.

","metadata":{}}, -{"cell_type":"markdown","source":"

For example, the answer to our initial problem is visibly seen from a graph to be near 1. Given this, the zero is found through:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["(0.7390851332151607, 0.0)"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["f(x) = cos(x) - x\nx = find_zero(f , 1)\nx, f(x)"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

For the polynomial $f(x) = x^3 - 2x - 5$, an initial guess of 2 seems reasonable:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["(2.0945514815423265, -8.881784197001252e-16, -1.0)"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["f(x) = x^3 - 2x - 5\nx = find_zero(f, 2)\nx, f(x), sign(f(prevfloat(x)) * f(nextfloat(x)))"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

For even more precision, BigFloat numbers can be used

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["(3.141592653589793238462643383279502884197169399375105820974944592307816406286198, 1.096917440979352076742130626395698021050758236508687951179005716992142688513354e-77, 0.000000000000000000000000000000000000000000000000000000000000000000000000000000)"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["x = find_zero(sin, big(3))\nx, sin(x), x - pi"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

Higher order methods

","metadata":{"internals":{"slide_type":"subslide"},"slideshow":{"slide_type":"subslide"},"slide_helper":"slide_end"}}, -{"cell_type":"markdown","source":"

The default call to fzero uses a first order method and then possibly bracketing, which involves potentially many more function calls. There may be times where a more efficient algorithm is sought. For such, a higher-order method might be better suited. There are algorithms Order1 (secant method), Order2 (Steffensen), Order5, Order8, and Order16. The order 1 or 2 methods are generally quite efficient. The even higher order ones are potentially useful when more precision is used. These algorithms are accessed by specifying the method after the initial starting point:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["(0.35173371124919584, 0.0)"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["f(x) = 2x - exp(-x)\nx = find_zero(f, 1, Order1()) # also fzero(f, 1, order=1)\nx, f(x)"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

The above makes $8$ function calls, to the $57$ made with Order0.

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["(-3.0, 0.0)"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["f(x) = (x + 3) * (x - 1)^2\nx = find_zero(f, -2, Order2())\nx, f(x)"],"metadata":{},"execution_count":1}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["(1.0000000027152591, 2.949052856287529e-17)"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["x = find_zero(f, 2, Order8())\nx, f(x)"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

The latter shows that zeros need not be simple zeros to be found. A simple zero, $c$,has $f(x) = (x-c) \\cdot g(x)$ where $g(c) \\neq 0$. Generally speaking, non-simple zeros are expected to take many more function calls, as the methods are no longer super-linear. This is the case here, where Order2 uses $55$ function calls, Order8 uses $41$, and Order0 takes, a comparable, $42$.)

","metadata":{}}, -{"cell_type":"markdown","source":"

To investigate an algorithm and its convergence, the argument verbose=true may be specified.

","metadata":{}}, -{"cell_type":"markdown","source":"

For some functions, adjusting the default tolerances may be necessary to achieve convergence. The tolerances include atol and rtol, which are used to check if $f(x_n) \\approx 0$; xatol and xrtol, to check if $x_n \\approx x_{n-1}$; and maxevals and maxfnevals to limit the number of steps in the algorithm or function calls.

","metadata":{}}, -{"cell_type":"markdown","source":"

Classical methods

","metadata":{"internals":{"slide_type":"subslide","slide_helper":"subslide_end"},"slideshow":{"slide_type":"slide"},"slide_helper":"slide_end"}}, -{"cell_type":"markdown","source":"

The package provides some classical methods for root finding: Roots.newton, Roots.halley, and Roots.secant_method. (Currently these are not exported, so must be prefixed with the package name to be used.) We can see how each works on a problem studied by Newton himself. Newton's method uses the function and its derivative:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["(2.0945514815423265, -8.881784197001252e-16)"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["f(x) = x^3 - 2x - 5\nfp(x) = 3x^2 - 2\nx = Roots.newton(f, fp, 2)\nx, f(x)"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

To see the algorithm in progress, the argument verbose=true may be specified.

","metadata":{}}, -{"cell_type":"markdown","source":"

Alternatively, Roots.Newton() can be specified as the method for find_zero. The functions are specified using a tuple:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["2.0945514815423265"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["find_zero((f,fp), 2, Roots.Newton())"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

The secant method typically needs two starting points, though a second one is computed if only one is give. Here we start with 2 and 3, specified through a tuple:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["(2.094551481542327, 3.552713678800501e-15)"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["x = Roots.secant_method(f, (2,3))\nx, f(x)"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

Starting with a single point is also supported:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["2.0945514815423265"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["Roots.secant_method(f, 2)"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

(This is like Order1(), but the implementation is significantly faster, as the framework is bypassed, and fewer checks on convergence are used. This method can be used when speed is very important.)

","metadata":{}}, -{"cell_type":"markdown","source":"

Halley's method has cubic convergence, as compared to Newton's quadratic convergence. It uses the second derivative as well:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["(2.0945514815423265, -8.881784197001252e-16, -1.0)"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["fpp(x) = 6x\nx = Roots.halley(f, fp, fpp, 2)\nx, f(x), sign(f(prevfloat(x)) * f(nextfloat(x)))"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

(Halley's method takes 3 steps, Newton's 4, but Newton's uses 5 function calls to Halley's 10.)

","metadata":{}}, -{"cell_type":"markdown","source":"

For many functions, their derivatives can be computed automatically. The ForwardDiff package provides a means. Here we define an operator D to compute a derivative:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["D (generic function with 2 methods)"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["using ForwardDiff\nD(f) = x -> ForwardDiff.derivative(f, float(x))\nD(f, n) = n > 1 ? D(D(f),n-1) : D(f)"],"metadata":{},"execution_count":1}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["2.0945514815423265"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["Roots.newton(f, D(f), 2) "],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

Or, for Halley's method:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["2.0945514815423265"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["Roots.halley(f, D(f), D(f,2), 2) "],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

Finding critical points

","metadata":{"internals":{"slide_type":"subslide","slide_helper":"subslide_end"},"slideshow":{"slide_type":"slide"},"slide_helper":"slide_end"}}, -{"cell_type":"markdown","source":"

The D function, defined above, makes it straightforward to find critical points (typically where the derivative is $0$ but also where it is undefined). For example, the critical point of the function $f(x) = 1/x^2 + x^3, x > 0$ near $1.0$ is where the derivative is $0$ and can be found through:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["0.9221079114817278"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["f(x) = 1/x^2 + x^3\nfind_zero(D(f), 1)"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

For more complicated expressions, D will not work, and other means of finding a derivative can be employed. In this example, we have a function that models the flight of an arrow on a windy day:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["flight (generic function with 1 method)"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["function flight(x, theta)\n \t k = 1/2\n\t a = 200*cosd(theta)\n\t b = 32/k\n\t tand(theta)*x + (b/a)*x - b*log(a/(a-x))\nend"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

The total distance flown is when flight(x) == 0.0 for some x > 0: This can be solved for different theta with find_zero. In the following, we note that log(a/(a-x)) will have an asymptote at a, so we start our search at a-5:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["howfar (generic function with 1 method)"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["function howfar(theta)\n\t a = 200*cosd(theta)\n\t find_zero(x -> flight(x, theta), a-5)\nend"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

To visualize the trajectory if shot at 45 degrees, we have:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":"Plot(...)","image/png":"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"},"metadata":{"image/png":{"height":480,"width":600}},"execution_count":1}],"cell_type":"code","source":["theta = 45\nplot(x -> flight(x, theta), 0, howfar(theta))"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

To maximize the range we solve for the lone critical point of howfar within reasonable starting points. In this example, the derivative can not be taken automatically with D. So, here we use a central-difference approximation and start the search at 45 degrees–the angle which maximizes the trajectory on a non-windy day:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["26.262308921132885"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["h = 1e-5\nhowfarp(theta) = (howfar(theta+h) - howfar(theta-h)) / (2h)\ntstar = find_zero(howfarp, 45)"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

This graph shows the differences in the trajectories:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":"Plot(...)","image/png":"iVBORw0KGgoAAAANSUhEUgAAAlgAAAGQCAYAAAByNR6YAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAAPYQAAD2EBqD+naQAAIABJREFUeJzs3XecFPX9x/HXzOz1XmgHRzk5unTkROkliCgWsGOJStQYoyY/0GgSNRpLjImaxBY1lliwx0aRqiKCCIgCCsIBAkc5rved+f7+WCUS2gHXdvf9fDx4wN7tzX5vmJ157/f7nc/XMsYYRERERKTO2I3dABEREZFQo4AlIiIiUsfqPGAZYyguLkYjjyIiIhKufHW9wZKSEpKSkigqKiIxMbGuNx+0ioqKSEpKauxmNHnaT7Wj/VQ7obCfvis1LN4Z+PPpTsPn+YZy/8GfnxABSZE//LFIioTECCisho0lhtwSqPb++/xWsdA2xiU7xUeHBIusRIsOCdAhwaJ1LDi2Vf+/ZBAJhWOqIWg/1UPAkgNzXbexmxAUtJ9qR/updoJtP5X7Dct2/ShQ7TJsLQt8r1085DS3mNDepmWMtV+I+iFIHS4QecawrQw2lBg2lgT+Xru7ho0lMHebx7by/z43JQrObGdxTpbNiNYWEQpbQXdMNRbtJwUsEZFGs7HY8GHeD4HK44s94BqI88GAZhYXdbTJaW4xsLlFq9i6CTe2ZdEmHtrEWwxpFfjanj2VpKbGAlDhN2wqDfR2fZRnmL7B46lvXFKj4Kz2gbA1PMPCp7AlckgKWCIiDWh7ueHlbz1e+NawdFdgrmrXZBjY3OJnXS1ymtt0T6HRAkyMz6JLMnRJtjglE+7sb7NyD0zf4PHytx7//NolPRrOam9zTpbF0FYKWyIHooAlIlLPiqoNr280vPCtx9xtBp8F4zItfj3CYUwbi+SophtQLMuidxr0TnO4q7/N8vxA2Jq+wePxtdAsGs7uYHP+cRaDW1pYVtP9XaRxVFdXs2nTpqAfNrRtm1atWpGQkFCr5ytgiYjUg0q/4b0tgVD1zmZDtQvDWlk8drLD2R0sUppwqDoYy7Lomw590x3uHmCzbLdh+obAMOKja2BUa4v7Bzr0Sgu+303qx3fffccFF1xAeXn54Z8cJM4880xuvvlmbPvQhRgUsERE6ojrGeZvN/x7vcdrGw3FNdA3He7qb3PecTat40IneFiWRf9mFv2bwb0n2Ly92fB/n7r0ed3PZZ0s/tDfISOEfl85cp7ncccdd5CcnMxDDz1EdHR0YzfpmNTU1LB8+XIefvhhAG655ZZDPl8BS0TkGG0vNzz4pccz33jkVcBxiXD98TbnH2fTJTn0Q4ZlWZzezuKUTIvH1njctszjpQ1+pva0+XVPm7iI0N8Hsr/du3fz+eefc9ddd9G7d+/Gbk6dOP744wF46KGHuO666w45XKiAJSJylDYUG/70hcfT33hE2nBpJ5uLOloMaBaec5EibItruztMzrb543KPP67weHytx539HS7OtlRTK8wUFhYC0KZNm0ZuSd3q06cPANu3bz9kwNJSOSIiR2jVHsOFc/1kT/fz2kaP3/Wx2Xy+j4cGOZzQ3A7LcPVjSZEW9w50+PocH0NaWfx0oUu/N/x8sNU7/A9LyPC8wP+34ziN3JK6FRERAfz39zsYBSwRkVr6ZIfH6TP99HzNz0c7DA+eaJN7vo/f9HGa9J2AjaV9gsWLI3wsnuAQF2Ex+j2X8TP8rC7QUmrStOTm5jJs2DCSkpLqbDhTAUtE5BCMMczc4jHsHT+D/uOyvtjwzFCH9ef6uLa7Q6xPwepwBja3+eg0h1dGOqwpNPR8zc9dy108rVkrTURiYiJ33nknL7zwQp1tUwFLROQAXM/wygaP/m/6GTvDpdwPb4x2+HKij4s72Vo25ghZlsXELJvVk3z8prfNbz/zGD/TJb9SIUsazv3338+UKVP2Pi4sLCQ9PR2Ak08+mbi4uDp7LU1yFxH5Eb9neG6d4Z6VLt8UwcgMiw/G2YzICM+J63UtyrG4o7/DoBYWF81z6fuGn1dGBuauSWgr9xvWFtbf9rskc9ge5SuuuIJOnTpx3333kZyczNNPP82ECRNITU2t8/YoYImIfG/uVo9ffuLyZQGc0c7iuWG2Lvz1ZGymzfKzLM6Z43Ly2y5/yTFc0003CISytYXQ7w1/vW1/2Zk++qYf+jnJyclMnDiRp556ihtuuIFHHnmEl19+uV7ao4AlImEvt8Twq8Uur+caBrWw+OwMh37NdKGvb5nxFgvGO0xd4nHtIo+PdhieGOwQr7pZIalLciAE1ef2a+O6667j9NNPp2vXrjRr1mxv2YW6poAlImGrrMZwz0qPP33hkR4N/x7ucP5xGgpsSJGOxV9PdDipRaCcw4A3/bw/1kf7BP0fhJpYn3XYHqaG0KVLF7KyspgyZQr33Xdfvb2O+r5FJOwYY3jpW48ur/j50xcevz7eZu0kHxd01BBVY5mUZfPZGT5qPBj8tp+vCzX5XerPlVdeid/vZ+LEiQCUl5fTpk0bJk2axOrVq2nTpg0333zzMb2GerBEJKws32345ScuH+YZzmhn8ecch6xEhaqmoHOyxYen+Rj9np/Bb/uZNc5Hby0cLfVg3rx5XHPNNXuLhsbGxvLdd9/V6WuoB0tEwsKuCsPPPgxUFM+vNMwe5/DGGJ/CVRPTKtZiwXgf7eIthr3j55Mdqv4udWfbtm106dKFzz//nOuvv75eX0s9WCIS0mo8wz9We/x+mYcF/PVEm6u7qY5VU5YWbTHnVIfxM11Gv+fy1hgY2Vr9AXLsMjIyWLt2bYO8lo5YEQlZH+1y6P2anxs+8Tgvy+abc3xc18NRuAoCiZEWM05xGNzSYtwMl/9sUk+WBBcFLBEJOdWuYeqnLmcsjCE1yuLzs3w8OtihWYyCVTCJ9Vm8OcbhtHYWZ812eWG9QpYEDw0RikhI+brQcME8P6v2wO97VPHbnHhs3RkYtKIci5dGOFyx0GXyfJekSDi1rfoGpOlTwBKRkGCM4Z9fG67/xKVNHHxyuo8OTo3CVQjw2RZPDnEoqnY5d47LgvGWCsFKk6ePASIS9PIrDWd/4DLlQ5cLO1p8fqZPF+AQ49gW/x7h0D3FYvxMP5tKVCdL6s7cuXM54YQT6NatG927d2fq1Kl43rENSStgiUhQm7PVo+drfhZsN7w+yuHxwT7itNRKSIr1Wbz9E4cYH4yb4aewSiFL6kZKSgovvfQSq1evZtmyZSxatIhnn332mLapgCUiQemHieyj33Ppmmzxxdk+zuygU1qoax5j8f5YH9sr4KzZLtWuQpbU3v3338+UKVP2Pi4sLCQ9PZ127dqRlZUFQHR0NL179yY3N/eYXktnIxEJOmsLDTlv+fnrlx73nmAza5xD6zj1WoWLzskWb412+HiH4YqFLsYoZEntXHHFFbz55psUFhYC8PTTTzNhwgRSU1P3PicvL49XX32V8ePHH9NraZK7iAQNYwyPr/W44ROPtvGweIKPvukKVuFocCubZ4bB+XNd2id43NHfaewmyWF41ZX4d2ypt+37WmRiR0Yf8jnJyclMnDiRp556ihtuuIFHHnmEl19+ee/3i4uLOe2005g6dSr9+/c/tvYc00+LiDSQ3ZWB3oq3Nhl+1sXmzzm25lqFufOOs8ktMdy81KNDgsVlnTUo05T5d2xh559/UW/bb/6rh4nMzD7s86677jpOP/10unbtSrNmzejTpw8AJSUljB07lgkTJnDjjTcec3sUsESkyftgq8fF812qXHhjtMMZ7XUhlYBpvWw2lBiu/tilb7pFLy0O3WT5WmTS/FcP1+v2a6NLly5kZWUxZcoU7rvvPgBKS0sZO3YsY8eO5dZbb62b9tTJVkRE6kGVa7hlqcefV3mMzLB4dphDhuZayY9YlsVDJzos2ennvLl+PjtDd5E2VXZkdK16mBrClVdeybXXXsvEiRMBePDBB1myZAllZWW8/vrrAEyaNIlbbrnlqF9DAUtEmqQ1BYGK7F8VwP0DbW443lbRUDmgaJ/FSyN99HvDzw2LXR4frEubHNq8efO45ppriIiIAOCWW245pjB1IDoKRaRJMcbw2BqPGxd7tEuATyf46KOJ7HIYXZItHjzR4coPXca09piYpWFk2d+2bdsYMWIEqampzJw5s15fa78jsKqqimuvvZbs7GyOP/54LrroIgB27tzJ2LFjyc7OpkePHixcuLBeGyYi4Wd3peHM2S5Xf+xxcbbNsjMVrqT2Lu9sMamDxZUfuqr0LgeUkZHB2rVrWbRoEQkJCfX6Wvv1YN10001YlsU333yDZVnk5eXt/XpOTg4zZsxg6dKlnHnmmWzcuHFv95qIyLGY/V1gInuNp4nscnQsy+LxwQ69X/dz4TyX+eMdfLYCujSOfQJWWVkZTz75JN999x3W93MdWrZsCcD06dNZv349AAMGDCAjI4MFCxYwatSoBm6yiISSKtfwm6UeD6zyGNXa4pmhmsguRy85yuKFEQ5D3nb5w3KP2/upPpY0jn0+In777bekpqbyxz/+kf79+zN48GDmzJlDfn4+NTU1e8MWQPv27dm8efNBN1xcXLzPn6qqqvr7LUQkKK0uMAx808/DX3ncP9Bm5ikKV3LsBrWw+X1fmzuXeyzcfmwL9srRs+1AxKipqWnkltStyspKAHy+Q09j3+e7fr+fTZs20a1bN+655x6WL1/O6NGj+eqrr464AZmZ+9ajmDp1KtOmTTvi7YSKgoKCxm5CUNB+qp1Q2E/vbvVx1dJoWsd6zBpeSc9kj8I6/rVCYT81hFDcT1e1gxmbYjh/jsfCUWWkRNbNdkNxX9WHgoICoqOjcRyHxx57jMsvvzzopxS5rsvWrVv5+9//TmRkJPHx8ezZs2fv93+83A78T8Bq27Yttm1z4YUXAtCnTx86dOjAqlWr8Pl85OXl7e3Fys3NpW3btgdtyJYtW0hMTNz7OCoqiqioqGP/DYPY/+58OTDtp9oJ1v1kjOGBVR7/96nHWR0snhkaQVzEoZe3OBbBup8aWijup5dHG3q97ueWrxJ5aWTd3TQfivuqPqSmpvLggw9y4403snjx4sZuTp3p168fjz/++D6jegeyzxGXnp7OyJEjmTlzJuPGjWPjxo1s3LiRrl27MmnSJB599FFuu+02li5dytatWxk6dOhBN5yYmLhPwBIR8XuGaz/2eGytx7ReNn8coNpWUn/axAdKN0ye7/LTzh5j2ujGiYaWk5PDrFmz2LZtG54X3MO1tm2TkpJCWlra3uHPQ9kv0j/66KNcfvnlTJs2Ddu2eeyxx2jdujX33nsvkydPJjs7m8jISJ5//vmg7+4TkYZTXG04Z47LnK2GJwY7XNFFFzupfxd2tHjqa4uff+yy6myLaJ8CfUOLj4+nU6dOjd2MBrdfwMrKymLevHn7PbFFixbMmjWrQRolIqFlU4lh/Ew/W8rg/VMcRrVWuJKGYVkWfz/Jodfrfu5d6fF73VUoDURnORGpV0t3eQx8y09pDSw63adwJQ2ua4rFr3va3L3SY32RCpBKw9CZTkTqzesbPYa+7dIhwWLxBB/dUjQ8I43j1j42rWLg5x+7GKOQJfVPAUtE6pwxhvu/cJn4gctp7SzmnurQIlbhShpPrM/i4UEOs7YaXtmggCX1TwFLROpUjWe46qNAGYabe9u8OMIhRhOLpQkY387mjHYW1y92Ka5WyJL6pYAlInWmqNpw6gyXp772eGqIw10DHJVhkCblwUEORdXwu2XBXTJAmj4FLBGpE7klhpP+42fpLsPMUxwu66zTizQ9beMtbutr8/BXHst3qxdL6o/OgCJyzJbsDNwpWO6HTyb4GKE7BaUJu/54m67JcPXHLp4mvEs90VlQRI7Jaxs9hr7jclyCxacTfHRJ1pCgNG0RtsU/TnL4dKcmvEv9UcASkaNijOG+lYE7Bc9oH7hTsFmMwpUEhyGtbMZlWvxumYvfU8iSuqeAJSJHrMYzTPnQZdoSj1v72Px7uKMlSCTo3Nnf4ZsieHadApbUPQUsETkihVWGU953eWad4V9DHf7QX3cKSnDqk24xqYPFbctcqlyFLKlbClgiUmsbiw2D/uPn83zDrFMcLumkU4gEtzv6O2wth8fWqGyD1C2dHUWkVhbvCNwpWO3BJ6f7GJah04cEvy7JFhdnW9y1wqOsRr1YUnd0hhSRw3plg8fwd106JQXWFOysOwUlhPy+r0NBFTz0lXqxpO4oYInIQRljuHuFyzlzXM5qb/HBOIf0aIUrCS3tEyymdLG5b6VHYZV6saRuKGCJyAHVeIYrFrr8ZqnH7/raPK87BSWE3dLHpsqF+79QL5bUDQUsEdlPlWs45wOX59YbnhnqcHs/B0t3CkoIaxVrcV0Pm79+6bGzQr1YcuwUsERkH5V+w1mzXd7/zvDGaIeLdaeghImpPW0cC+5eoV4sOXY6c4rIXuV+w2mzXOZtM7w9xuHUtjpFSPhIjbb4dU+bR9Z4bClVL5YcG509RQSAkupAAdFPdhjeP8VhdBudHiT8XN/DJiEC7l2pXiw5NjqDigiFVYYx77usyDfMGucwtJVODRKeEiItru1m8/Q3Hnsq1YslR09nUZEwt6fSMOo9l6+LDHNOdRjUQqcFCW9Xd7NxDTy+Vr1YcvR0JhUJY7sqDMPf9bOp1DD3VB/9m+mUINI8xmJyR4uHv/Ko1hqFcpR0NhUJU9vLDcPe8bOzAuaf6qN3msowiPzg+h4O28ph+gYFLDk6ClgiYei7UsPQt/0U1cCC8T66pypcifxY91SLsW0sHljlYoxClhw5BSyRMJNbYhjyTmDR5oXjfXTSuoIiB3Tj8TbL82HBdgUsOXIKWCJhZH2RYcjbfmwLFp7mIytR4UrkYEa1tuiRAn9epcnucuQUsETCxJqCQM9VXESg56ptvMKVyKFYlsWNxzu8s9nwdaF6seTIKGCJhIEv8g1D3/GTFhWY0J4Rp3AlUhsXdLRoEQN//VK9WHJkFLBEQtznuwOlGNrEwbzxPlrEKlyJ1FaUY/HzbjbPfOOxW4VH5QgoYImEsE93eox410/HRIs5p/pIj1a4EjlSV3W1McBja9SLJbWngCUSoj7c7jHqPZceKRazxzmkRClciRyNZjEWF2fb/O0rjyq3sVsjwUIBSyQEzd3qMXaGy4B0ixmnOCRGKlyJHIvre9jkVcDr3/kauykSJBSwRELMjC0ep850GdzS4t2xDvERClcix6prisW4TItH1kWq8KjUigKWSAj5zyaPCbNcRre2eGuMQ4xP4Uqkrvyiu81XRQ5LdylgyeEpYImEiFc2eJw92+X0dhavjnKIchSuROrS6NYWrWI8nv5GAUsOTwFLJAQ8v87jvLku52RZvDjCIVLhSqTOObbFeW1rePFbjwq/QpYcmgKWSJB7bp3HxfNdLsm2eHaYg89WuBKpLxe0r6GoGt7IVcCSQ1PAEglib+Z6XLbA5bJOFv8c4uAoXInUq6x4w+CWFk9/o5pYcmgKWCJBas5Wj3PnuJzV3uLxwQ62pXAl0hB+2tlmzlbDphL1YsnBKWCJBKGl+TYTZrmMyLB4frh6rkQa0sQOFrE+eGaderHk4BSwRILMqj2G8z6OpU+axWujNaFdpKHFR1icm2Xx9NcenmpiyUEoYIkEkfVFhjHv+Wkb5/HOWIdY1bkSaRSXdbbJLYUF2xWw5MAUsESCxHelhlHv+UmKhOknVZCk5W9EGs1JLSyyE+HprzVMKAemgCUSBHZXGsa878cAs8f5aBatT80ijcmyLC7rbPPqRkNRtd6Psj8FLJEmrrjaMPZ9l/wqmH2Kj8x49VyJNAUXZ9tUeTB9gwKW7E8BS6QJq/AbTpvpsr7YMOsUH52SFa5EmorWcRY/aWPxlIYJ5QAUsESaqGrXMPEDl892G94b69ArTeFKpKm5rJPN4p2GNQXqxZJ97Rew2rdvT+fOnenduze9e/fm5ZdfBmDnzp2MHTuW7OxsevTowcKFCxu8sSLhwvUMlyxw+WCr4c3RDoNa6LOQSFN0ejuL1ChU2V324zvQF19++WV69+69z9duuukmcnJymDFjBkuXLuXMM89k48aNRERENEhDRcKFMYaff+wxfYPhlZEOo9soXIk0VVGOxYUdbZ5b5/HHAbbWApW9an3mnj59OldddRUAAwYMICMjgwULFtRbw0TC1c1LPR5b6/HkEIezOihciTR1P+1sk1cBM7ZomFD+64A9WJMnTwbghBNO4J577sG2bWpqamjZsuXe57Rv357NmzcfdMPFxcX7PI6KiiIqKqou2iwSsu5Z4XLvSo+/nmhzaSeFK5Fg0DvNonsKTN/gMb6d3rcSsF/AWrhwIW3btqWmpoZbb72VSy65hOeee+6IN5yZmbnP46lTpzJt2rSjb2mQKygoaOwmBIVw3k9PfRvBzSuimda1iskZ1ezZc/DnhvN+OhLaT7Wj/VR7B9tXp7aM5JF1kWzftYcop4Eb1QSF4zGVmpq6z+P9Albbtm0BiIiI4Prrr6dTp06kpaXh8/nIy8vb24uVm5u797kHsmXLFhITE/c+Vg/W/jtfDiwc99ML6z2mrnC5vofN3TlxWFb8YX8mHPfT0dB+qh3tp9o70L6a3M1w3xo/n1ckc2pb9WKBjql9joKysjIKCwv3Pn7xxRfp06cPAJMmTeLRRx8FYOnSpWzdupWhQ4cedMOJiYn7/An3cCVyMG9v8rh4vsulnSz+nGNjWZokKxJsuqdAl2R4daPuJpSAfXqwduzYwdlnn43ruhhjyMrK4tlnnwXg3nvvZfLkyWRnZxMZGcnzzz+vOwhFjtH8bR6T5rhMaGfx+GAHW+FKJChZlsXEDjZ/+8rjsZMNkY7ey+Fun4CVlZXF8uXLD/jEFi1aMGvWrAZplEg4WLrL47RZLkNaWrwwwtHt3SJBbmIHmzuXe8zdZhibqfdzuNNAsUgj+GpPYH3BnqkWb4x2iNKnXZGg1zMVshM1TCgBClgiDWxDsWH0+34y4+DdnzjERShciYQCy7KYmGXzRq6hxlNNrHCngCXSgLaVGUa/5yfeBzNP8ZEcpXAlEkomdrDZUwXztylghTsFLJEGkl9pGPO+n2oPPjjVR4tYhSuRUNMnDbIS4NWNCljhTgFLpAGUVBtOmeGyswJmj/PRNl7hSiQU/XA34eu5Hn4NE4Y1BSyRelbpN0yY5fJ1oWHmKT66JCtciYSyiVkWuyth4XYFrHCmgCVSj2o8w7lzXRbvNLw71qFPusKVSKjrn27RLl7DhOFOAUuknhhjuGKhy/tbDK+Pdji5pd5uIuHgx8OEroYJw5bO+CL15I7PPZ5dZ3h2mMPYTL3VRMLJxA4WOyrgox0KWOFKZ32RevDcOo/bPvf44wCb847T20wk3AxsbtEmDl7XMGHY0plfpI4t2O5x+UKXyztb3NRLbzGRcGRZFuPb2ry3RVXdw5XO/iJ16OtCw5mzA+sLPnKyg6XFm0XC1rhMi/XFsK5IvVjhSAFLpI7sqjCMm+GnVQy8OsohQos3i4S1ERkWkTbqxQpTClgideCHWldlfnh3rJbAERGIi7AY1srivc3qwQpHClgix8gzhksXuKzIN/xnjEP7BIUrEQkY19Zi/nZDWY1CVrhRwBI5Rrd+5jF9g+Hfwx1OaK63lIj817hMm2oP5mrx57Cjq4HIMXhyrcfdKzz+NNDmzA56O4nIvrKTLDomwntbFLDCja4IIkfpg60eV33kclVXmxuP11tJRA5sXGagXIMxClnhRFcFkaPw1R7D2bNdRrW2eHiQrXIMInJQ4zItNpfC6oLGbok0JAUskSOUV244daaf9gnw8kgHn8oxiMghDG1lEeOoXEO4UcASOQLlfsPps1yqPXjnJz4SIxWuROTQon0WI1tbvKt5WGFFAUukljxjuGiey+oCwzs/8ZEZr3AlIrUzLtPiozxDUbVCVrhQwBKppamfery1yfDSCIe+6QpXIlJ7p2TauAZmf6eAFS4UsERq4ZHVLn9e5fHXHJvx7fS2EZEj0z7Boluy5mGFE10pRA7j/S0e1y7yuK67zS96OI3dHBEJUuPa2ry/xeCpXENYUMASOYSV+YZz5ricmmnxQI7eLiJy9MZlWuRVwIr8xm6JNARdMUQOYmtZoBxDdiK8MMLBUTkGETkGJ7WwSIiA9zZrmDAcKGCJHEBpjeG0mX4sAuUY4iMUrkTk2EQ6FiMzLGZqontYUMAS+R+uZzh/rsu6Ynj3Jz4y4hSuRKRujMiw+HSXodyvkBXqFLBE/scNiz3e32J4ZaRDzzSFKxGpO8MzbGo8WLRDASvUKWCJ/MhDX7o8/JXH3wbZjM3U20NE6lb3FEiPhnnbFLBCna4gIt/7zyaP6z/x+HVPm6u6qRyDiNQ9y7IY1spSwAoDClgiwLJdgXlXZ7a3uPcEvS1EpP4Mz7BYustQWqOQFcp0JZGwt7nUMH6mn+4pFs8Nd7AtzbsSkfozvJWN38DHeQpYoUwBS8JacXUgXEU58PYYh1ifwpWI1K8uydAiBuZtV8AKZb7GboBIY6nxAlXaN5fCotN9tIhVuBKR+vfDPKz5ClghTT1YEpaMMfziY485Ww2vjnLolqJwJSINZ3iGxWe7DCXVClmhSgFLwtKfV3k8ttbj0ZMdRrXW20BEGtbwVjaugQ81Dytk6coiYee1jR7/96nHzb1tLu+it4CINLzsJMiI1TysUKari4SVT3d6XDTP5dwsizv76/AXkcZhWRbDMyzmqx5WyNIVRsLGphLD6bNc+qZb/GuoyjGISOMa1srm83xDkeZhhSQFLAkL5X7DGbP9xDrw5miHaJVjEJFGNjzDwjOwUMOEIUkBS0KeMYYrFrp8XQhvjvHRLEbhSkQaX1YCZMahcg0hSnWwJOT9eZXHi98aXhrh0CtN4UpEmoYf5mHN2+YBWv801KgHS0LarO88pi3xmNbL5tzjdLiLSNMyrJXNinzYU6lerFCjK46ErG+LDefNdRnT2uIu3TEoIk3Q8AwLAyxUPayQo6uOhKTSGsMZs/ykRcELIxwcW0ODItL0tE+waB+veVihSHOwJOQYY7h0gUsyN/R6AAAgAElEQVRuKSw+3UdKlMKViDRdgXpYmocVatSDJSHn7hUer200PDvUoXuqwpWING0ntbBZVYDWJQwxBwxYTz/9NJZl8eabbwKwc+dOxo4dS3Z2Nj169GDhwoUN2kiR2np3s8etn3n8rq/NmR30+UFEmr6c5oF6WEt3KWCFkv2uQLm5uTzxxBPk5OTs/dpNN91ETk4O69at4+mnn+aCCy6gpqamQRsqcjhfFxoumOsyvq3F7/sqXIlIcOiaAokRsHinAlYo2ecq5HkeV1xxBQ8//DBRUVF7vz59+nSuuuoqAAYMGEBGRgYLFixo2JaKHEJRtWHCLD8ZcfD8cC2DIyLBw7YsBja3FLBCzD6T3B944AFOOukk+vXrt/dr+fn51NTU0LJly71fa9++PZs3bz7khouLi/d5HBUVtU9oE6krnjFMnueyvRyWnOEjMVLhSkSCS05zi0fXeBhjsPQBMSTsDVhffvklr732Wp3Nr8rMzNzn8dSpU5k2bVqdbDsYFRQUNHYTgsLR7Kd7VkfyzuZIXhhUQTPPZc+eemhYE6PjqXa0n2pH+6n26mtf9Yh12FUZy+dbCukQH/w9WeF4TKWmpu7zeG/A+vDDD8nNzSU7OxuAvLw8pkyZwu23347P5yMvL29vL1Zubi5t27Y95Att2bKFxMTEvY/Vg7X/zpcDO5L99MZGjz+tcbmrv8153ZPqsVVNj46n2tF+qh3tp9qrj301MtbAx37WVifRLzU05pCG+zG193/x6quvZvv27eTm5pKbm0tOTg6PP/44V199NZMmTeLRRx8FYOnSpWzdupWhQ4cecsOJiYn7/An3cCV176s9hosXuEzsYHFz79A4IYlIeEqLtuiUBIt3BH/vlQTUqtDovffey+TJk8nOziYyMpLnn3+eiIiI+m6byEEVVBnOmO2nfTw8PdTRnAURCXo5zS0+0UT3kHHQgDV//vy9/27RogWzZs1qiPaIHJbrBcox5FfB0jN8xEcoXIlI8DuxucUL6z3K/YZYn85rwU7jKhJ0bvnMY9ZWw0sjHI5L1ElIREJDTgsbv4HPd6sXKxQoYElQeflbj3tXetx7gs2YNjp8RSR09EiBOB98onlYIUFXKAkaK/MNly1wOf84i18dr0NXREKLz7YY0EwFR0OFrlISFHZXGs6Y5adLMvxziCa1i0ho+mGiuzEKWcFOAUuaPL9nOHeOS6kf3hjt0+RPEQlZOc0ttpfDlrLGbokcKwUsafKmfuqxYLvhlZEO7RIUrkQkdOU0D5zjVA8r+ClgSZP23DqPv3zp8Zccm2EZOlxFJLS1iLXokIDmYYUAXbGkyfpsl8eVH7pc2sni2u46VEUkPOQ010T3UKCrljRJO8oNZ8526Zlq8chJmtQuIuHjxOYWy3YbqlyFrGCmgCVNTrVrmPiBS40Hr49yiNakdhEJIzktLKo9WJGvgBXMFLCkyblhscenuwyvjXJoE69wJSLhpVeqRZSjeVjBTgFLmpTnNkbwj9UefxvkcFJLHZ4iEn4iHYt+6ZYqugc5XcGkyfhkh8fUFVH8rIvNlK46NEUkfJ34fcFRCV66ikmTsLMiMO+qd4rHQ4N0WIpIeDuhmcXmUthVoZAVrHQlk0bneobz57q4Bp4aWEGko3lXIhLe+qQHzoOa6B68FLCk0f1+mcf87YYXRzi0itHJRETkuESIj1DACmYKWNKo3t3scdcKjzv72wxXpXYREQBsy6JXqsVyBaygpSuaNJpNJYbJ813Gt7WY1kuHoojIj/VOU8AKZrqqSaOocg2T5rgkRcAzQx1sVWoXEdlHnzSLrwuhrEYhKxgpYEmjuHGxx8p8wyujHFKjFa5ERP5Xn3QLA6zao4AVjBSwpMG9sN7jH6s9HjzRpn8zHYIiIgfSPQV8FhomDFK6ukmDWl1gmPKhy0UdLX6mYqIiIgcV5Vh0S4EV+Y3dEjkausJJgymtMUz8wE/7BHj0ZAdL865ERA5JE92DlwKWNAhjAj1Xm0vh1VE+4iIUrkREDqdPmsWqPQa/p5AVbBSwpEE8ssbjxW8NTw5x6JKscCUiUht90i0qXfi6sLFbIkdKAUvq3ZKdHtd/4vGL7jbnHqdDTkSktnqlBj6Qapgw+OhqJ/UqvzJQ76pvusX9A3W4iYgcieQoiw4JWjInGOmKJ/XGM4FK7WU1MH2ko0WcRUSOgia6BycFLKk3d6/wmLHF8Pxwh7bxClciIkejz/cByxiFrGCigCX1Ys5Wj98t8/htX5uxmTrMRESOVp80i4Iq2FLW2C2RI6Ern9S5rWWG8+e6jMyw+F0fHWIiIseid9r3E913qwcrmOjqJ3WqxjOcO8cl0oF/D3dwbA0Niogci9ZxkB6tOwmDja+xGyCh5eYlHp/uNCw4zaFZjMKViMixsiyL3mmW7iQMMurBkjrz+kaPP6/y+NNAm0EtdGiJiNSVPrqTMOioB0vqxLoiw2ULXCZ2sPhlD4UrkWBnXBevogSvogw8D4wBvr/A//hutu//bfZ+70fftyzsmDjsuESsyGitP3oM+qRZ/OmLQG3BtGjtx2CggCXHrMIfWMS5RQw8OUSLOIs0Jcb145UV45WX/PdP2Y/+XV5KVeFudvmr93meqSyv24Y4Edhx8dixCdixiYG/4xK+/zvxf/5OwIlLwk5M1fnkez9MdF+ZbxjRWvskGChgyTG79mOXdUXw6Rk+EiP1xhdpaF55Cf78PPy7t+PP346bn4c/fzv+3dtxC3aB8fb7GSsqFjs2HjsuARMRjZ2Uii+t5fcB6EdhJyYObOf7H/qf9/fex9Z/g9Dep1gYz8NUlB4g2AWCnD9v8z7Bj/+p82RFxeBr3oaIFpn4WrQlonkbfC0y8aVnYPki6mz/BYNOSRDjBCa6j2jd2K2R2lDAkmPy1NceT31jeGaow/GpClci9cG4Lm7hLvy7t+HPz9snQPnz8zAVpXufa0XH4UtvhS+tJbF9huKktsBJSts3NMXGYzn/Pf3v2bOH1NTUxvjV9jKeh6ks2xvC3JI9+HdupWbHZvw7v6Ni9RJM+fe/p23jS2sVCFvNM78PYJlENM/Ejo1v1N+jvji2RU9NdA8qClhy1FbkG37+scuVXSwu7qR5VyJ1wS0tombrt9Rs3UDN1m+p3vot/p1bwXMDT7BsnJRm+NJaEZmZTUzvwYGwkdYSX3or7NiExv0FjpJl21jf954diDEGr7QI/84t1OzYgn9H4O+KFQspLdi5t/fLTkjB17wNkZnZRGX3Iuq4HtjRcQ35q9SbPmkWH+bt3xspTZMClhyVourAvKuuyfDQiU5jN0ck6BjPw92TR/X3Qarmu0Cocot2A2BFRhPROouojj2JP/n0QK9UeiuclOb79D6FC8uycBKScRKSiTru+H2+51VX4t+59Ufha3MgeM1/HSybiMxsorN7EZXdi8gO3bGjohvptzg2fdIsnlgbmPca49OIQVMXfu9SOWbGBO4Y3F0Js07xEa03usghGc+jJi+Xms3r9vZK1WzdiKkKTCS3E1OIbN2R2AEjiWh9HBGts/Clt8Ky9eGlNuzIaCLbHEdkm+P2fs0Yg7t7O5XrV1L1zQrKlsymZM50cHxEtutMVMdA4Ipq3xUrIrIRW197vdLANbC6APo1a+zWyOEoYMkRe2CVxxu5hrfGOGQlKlyJ/C9TU0315m+o2vAl1Ru/omrDakxlGVgWvmZtiGidRXS3gUS2ziKidRZOYuPOfwpFlmXha5ZBfLMM4k88BWMM/h2bqVq3kqp1Kyn76G1KZr0AvgiiOnQLhK2OvYhs26nJTqDvmhw4364pNPRrpnNvU6eAJUfkozyPaUs8pva0Ob2d5l2JQOAuvqqNq6ne8FUgVG1eB24NVlQskR26kjDibCI7dCeybeegHZ4KdpZlEdGyHREt2xE/+PRAr+L2XKrWraBq3UpK5r5K8XvPYkVGEZl1PLF9hhDT66QmNX8rMdKidRysLtRE92CggCW1trvScN5cl5NaWNw1QOFKwpe/YBfVG76kasNXVG/4kpq8TWAMdmIqUVk9SJ4wlMis7kS06oDlaJivKbJsm8jWWUS2ziJh2FkY16Vm63qq1n1BxeolFLz0Fwpe/Rsx3XOI7T+c6C79m0TPVrdkizUFCljBQAFLauWHeVdVLrwwwsGnRZwljHiVZVR9s4LKtcuoXLsMd88OAHzNM4nK6k788IlEZXXHSWupwphBynIcItt2JrJtZxJGTsJfuIuKz+dT/tlc8v95O3ZsAjG9h+B26o9JyWm0/+duKRbvb9GdhMFAAUtq5cEvPd7ZbHjnJw6t43QBkdBmPI+ard9SueYzKtcuozp3DXguvmatiek+kKjs3kRmdcOJT27spko98SU3I2HEJBJGTKJm20bKl82jfNk83EXvkpfWkti+w4jtP5KIFpkN2q6uyfC3r6DKNUQ5Ohc3ZQpYcljLdhmmLvG48XibU9tqaFBCk1tSQOXaZVStXUbl15/jlRZhRcUS1ak3yWdfQ3SXfvjSWjZ2M6URRGR0ICmjA4mnXsruFZ/g+2YppR++Tcnsl4jIzCa23/BAUdektHpvS7dkC9fAuiLooXsjmjQFLDmk4mrDuXP99Eq1uFvzriSEGH8NVRtXfx+ollHz3bcARLTpSFzOWKK79ieyfdewrDklB2bZNk77rqT0PYnks6+hcvUSypbNpejtpyl665/E9B5Mwshz9ikXUde6pQR6rVYXGHpo9Ywmbb8zx5gxY8jLy8O2bRISEnjooYfo06cPO3fu5OKLL+bbb78lKiqKf/zjHwwZMqQx2iwNxBjD1R+57KyAmac4RKo7WoKcV1VB5ZqlVHyxiMrVSzCV5djxSUR37kv8sLOI7twXJyGlsZspQcCKiCSm18nE9DoZr7yE8mXzKJn3Gjvv/zlRnfuSMPIcorJ71flcrbRoi2bRgVIN0rTtF7CmT59OcnJgXsEbb7zBpZdeysqVK7npppvIyclhxowZLF26lDPPPJONGzcSEdH4d1VI/fjXN4YXvjW8OMLhONW7kiDllZVQ8dViKr74mMq1y8BfQ0RG4M6x6O4DiWh9HJat3lk5enZsAvGDTydu0KlUrFhIyZxX2P2Pm4jIzCZh5DnE9BxUp0Vju6VYKtUQBPYLWD+EK4CioqK96Xv69OmsX78egAEDBpCRkcGCBQsYNWpUAzVVGtKaAsO1i1wu72xx3nG6+EhwcQt3U7FqEZWfL2DbpjVgDJHtu5J06qXEHD8IX3qrxm6ihCDLcYjtN5yYvsOoWruMkrmvsOdfd+Fr1pr44WcTN2BUnVSN75asNQmDwQEnF1x88cXMmzcPgPfee4/8/Hxqampo2fK/Ezzbt2/P5s2bD7rh4uLifR5HRUURFRVVF22WelbhD8y7ahcPDw1SDR8JDv5d26hY9TEVKz+metNasB3s9t1IPvvnxPTIaZAJyCIQKGoa3bU/0V37U735a0rmvELhKw9T/P5zxA+ZQPxJ47Fj4496+12T4cmvwe8Zlcxpwg4YsJ599lkAnnnmGaZNm8Zzzz13xBvOzNz31tWpU6cybdq0o2hiaCgoKGjsJtTar5dHsa4wgtkjyqks9qhswNcOpv3UmLSfArw9ebirPsa/Zglm5xbwReJ07EXkGdfgZPemsLKG6JQUql1gz57Gbm6TpeOp9o54X8U3w5pwDdEnn0nNJ+9QPON5ime/jK/fCHwDT8E+imWS2vgcqr1YPt9SSMeEpjlUGI7HVGrqvv+Xh7w95pJLLuGqq64KPNHnIy8vb28vVm5uLm3btj3oz27ZsoXExMS9j9WDtf/Ob4pe2+jx9AaXR0+2OblD49T4CYb91BSE637yykspX7GQ8qUfUL1xNVZ0LDE9cogZfylRXfphR/53KRprz56w3U9HSvup9o5qX6WmQnZ33KIrKF34FqUfv4N/yUziTz6NxDEXYMcl1HpTOdEG8LPdJHFCatOdwhHux9Q+AauwsJDy8nIyMjIAePPNN0lLSyM1NZVJkybx6KOPctttt7F06VK2bt3K0KFDD7rhxMTEfQKWNH25JYbLF7pM6mAxpUvTfdNK+DGuS+XXyyhfOoeKVYvAdYnq3JfUi28ipseJWJHh/eFNgoeTlEbSaT8lYfS5lC58i5I5r1C2dDaJYy4k/uTxtVqOp2UMJEUG1iSc0ABtlqOzT8AqKipi0qRJVFRUYNs2zZo145133sGyLO69914mT55MdnY2kZGRPP/887qDMITUeIbz57qkRMLjgx0t9yFNQs22jZQt/YDyZXPxigvwtWpP0rhLiO03XHOqJKjZ0XEkjrmAuJyxFL//HEVvPUHZR2+TdPrlRB8/6JDnYMuy6JZssVprEjZp+wSsdu3asWTJkgM+sUWLFsyaNatBGiUN77efeXy2y/DR6Q7JUQpX0njcksLAsiRLP6Bm67fYcUnE9htG7IBRRLTpqPAvIcVJTCXl3F8SP2QChW89Qf5TfyAyqwfJZ0whsm2ng/5c12RYqWmFTZpKFAuzvvO4d6XHfSfYDGyuoUFpeMZfTcWXn1K+9AMq13wGlkVM94EknnIR0V0HqJq6hLyIVu1pdtVdVK75jMK3nmDnA9cR2284SadfccDe2m4pFi9t8PCMwdaHjiZJZ60wl1dumDzf5SdtLH7VU+FKGo4xhupNX1O+9APKl8/HlJcS0bYzyWddRUyfoThxmsMp4Se6a39adOpD2aczKX7vGSrunkLyhCuIzRm7T+9ttxSLcj9sKYV2tZ8fLw1IASuMeSYQrmzg2WGOPgVJg/AX7KL8szmUL/0A/87vcJLSiT9xXGAIsOXB70wWCReW4xA/aBwxvU6m6K0nKHj5Qco+m0vKub8konkbALomf78mYaGhXYLO3U2RAlYYu3elx5ythtnjHJrH6A0q9cerqqBi5ceUf/YBVetWBtZx6xlYMDcqu1edLiMiEiqcuERSL/gVsf2GUzD9YXbcdzWJP7mQhBETaRvvEOsLLPp8SubhtyUNTwErTC3a4fHbzzx+09tmZGsNDUrdM55H1berKF8ym4qVH2GqK4nq2JOU824gptfJ2NGxjd1EkaAQ3bkvLaY9EihS+t6zVCxfQMp519M1+Tgt+tyEKWCFoT2VgZIMOc0tbuuncCV1yysvoWzxTEo/eht3zw6c9FYkjJxEbP+R+NJaHn4DIrIfOzKa5NOvILbPUApe/is7/3IDv846jUfMxehS3jTpfyXMGGO44kOXkhp4YYSjdaykztTs2ELpwrcoXzob47rE9hlK3EVTiezQTaUVROpIZGY2zW94iNIFr5Pz7nO02Lqc6pybiczo0NhNk/+hgBVmHlnj8Uau4Y3RDm3jddGTY2M8j8q1yyhd+CZVa5dhJ6SQMGIScYPG4RzFGmsicniW45AwYhKLkvrjTL+HnQ/8kuQzphB30qn6MNOEKGCFkRX5hhsXe1zbzeaM9hoalKPnVVVQvmQ2pQvfwr9rKxGZ2aRc+Gti+wzB8kU2dvNEwkKH49rTK+vPLIn+F7z6Nyq//pyU865XiZMmQgErTJTWGM6b46drMvxpoMKVHB1/fh6lC9+i7NOZmOpKYnqeRMr5N2oYUKQRZCWC54tiQf+rubxvPwpefICdf7qG1IumEtWxZ2M3L+wpYIWJXyxy+a4Mlp3pI9qnC6HUnjGGqvVfULrgTSq/WowVE0f8SeOJO3k8vpTmjd08kbDlsy06J8PqAog5+UQiMv/BnufuY9ffbyJh9Hkk/uRCLEclUBqLAlYYeH6dx7++MTwz1KFzssKV1I6prqL883mULnyLmm0b8bVsR/KkXxDbfwR2ZHRjN09ECBQcXf19qQZfcjOa/fweSj54meIZz1O1bgVpl/wGJzm9kVsZnhSwQtw3hYarPnK5ONvi4k4aGpTDcwt3U/rxO5Qteh+vvJjobieQNOFKojr10TCgSBPTLdli/nZv72PLdkgccwFRHXux59m72fHAdaRf/nsi23VuxFaGJwWsEFblGs6b6ycjFv5+krqJ5dCqctdQuuBNKlZ+hBURRdzA0cQPnoCvWUZjN01EDqJbisXOCsivNKRF//cDUFRWd5rf+BD5T/2BnQ//mpTzrieu/8hGbGn4UcAKYVM/9fiqAD49w0d8hHoeZH/GX0PFyo8oWfAmNZu/xklvRdKEK4kbOBo7Oq6xmycih7F3TcICw+BW+57nncRUml17LwXTH6bg+T9Rsy2XpPGXammqBqKAFaL+s8njoa88Hh5k0ztN4Ur25ZYWUrboPUo/egeveA9RnfqQduXtRHcdgGVrKFkkWGQngQV8UwSDW+3/fcsXScr5NxKR0YGit/6JPy+X1Mk3YcfoA1R9U8AKQVtKDZctcDmjncXPu+liKf9VvXUDpQvepPzzeViWTWz/EcQPmUBEq/aN3TQROQpRjkXbeFhXfPA1CS3LImHYWUS0aEv+M3ez8683kH7FbRr+r2cKWCHG7xkumOsS54MnhzialCwYz6Xyy8WULHiT6m9X4SQ3I3HsZOJOHKuChCIhIDvJYv0hAtYPorv2p/mND5L/z9vY8ZfrSLvkN0R37tsALQxPClgh5o7PPT7ZaVgw3iE1WuEqnBnXpXz5fEpmvYh/53dEduhG6qW/Ieb4k1QbRySEZCdafLzDO/wTgYjmbWh+/V/Jf/Yedj92KynnXk/cwDH13MLwpIAVQuZt87hzuccf+tuc1FJDg+HKuC7ly+ZRMvtF/Lu2Et19IKkX/p9u0xYJUR0T4Zl1gaLAtRm1sGPjSZ9yO4Wv/p2CFx/AKy8hYfjZDdDS8KKAFSLyKw2T57sMz7C4qZfCVTgyrp/yz+ZSPPtF3N3bie5xIqkX30RkZnZjN01E6lF2kkW5H7aVQ+tazl23bIfkSb/Ajkuk6K0n8EqLSBx/maaV1CEFrBBgjOFnH7mU++HZYQ6OrTdIODGun/KlH1A8+2Xc/O1E9xxE2qW3EtnmuMZumog0gOykwDl/XZGhdVztz/+WZZF06qWBkPXm43hlxSSf8wuVcagjClgh4OlvDK9tNLw6yjmiN5cEN+OvoWzpB5TMfgl3zw5iep1MwuW/JTIjq7GbJiINKCsBbAvWFcOwo7gxMGHYWdixCRS89Be8ilJSJ0/F8kXWfUPDjAJWkFtXZLhukcvlnS3O7qChwXBg/NXUfPYBeZ+8g1u4i5heg0m88naVWhAJU5GORbt4WF90+DsJDybuhNHYsfHk/+uP7H78d6T99HfY0bF12Mrwo4AVxGo8w0XzXFrFwl9PVJduqDP+asoWz6Tkg+m4hbuJ6TOExDF3KFiJCB0TrUPWwqqNmB4n0uyqu9j9z9vY9fdppP/sTpz4pDpqYfhRwApid3zusWy3YdHpjpbCCWGmppqyxTMCwap4DzF9h2JOGEda5+Mbu2ki0kRkJ1ks3F67Ug2HEtWxJ82uvY/dj97Crr9Po9nP71XIOkoaUwpSH273+OMKj9v72ZzQXP+NochUV1Gy4E2233kZha8/SlR2L1rc9Bhpk6dhN2vd2M0TkSYkOxHWF4Nnjq0XCyCyTUeaXfsnvJJCdj/yG7zykjpoYfhRD1YQKqoOlGQY1FwlGUKRV11J2aL3KJn7Cl5pEbH9RpAw5nwiFKpE5CCykywqXdhaBpnxx769iJZtaXbN3ez621R2PXoLza6+W+sXHiEFrCD0849dCqpgwXiVZAglXlUlZYvepWTuq3hlRcT2H0Xi6PO0XpiIHFZ2YuBasL7YkBlfN9eFiIwOpF/9R3b942Z2P/5b0q+6Czsqpk62HQ4UsILMv9d7/Hu94d/DHdolKFyFAq+qkrKP3w4Eq/JSYk8YReKo8/Clt2rspolIkGj/Q6mGIhheh5/JIjOzaXbVXez6x83kP/F70qbcgR0ZXXcvEMIUsIJIbonhmo9cLuxocUFHDQ0GO6+qgtIP36Z03mt4lWXEnTCahFHn4ktr2dhNE5EgE+lYtI/nmO8kPOC223Um/Wd/YPejt5D/5B2kX3EbVoTqZB2OAlaQcD3D5HkuKVHw95NUkiGYeZVlgWA1/3W8ynLiBv6EhFHn4Ett0dhNE5Eglp1kse4YamEdSlRWd9KuvJ3dj/+W/Kf/QNpPf4fli6iX1woVClhB4p6VHot2GhaMd0iK1NBgMPIqyij98C1K5r+Oqaoi7sSfkDDyXHwpzRq7aSISArITLeZuO/ZSDQcTnd2L9Mt/z+4nbiP/mbtJu/Q3WI5ixMFozwSBJTs9fr/M4ze9bU5uqaHBYOOVl1K68C1KFryBqaki7sRTSBg5CV+ygpWI1J3jEuGfXwfWp62vRZuju/Qj7ae3kv/kHRS++neSz7lOC0QfhAJWE1daY7hgnku/dIvf9VW4CiZeVSWl81+jZN7rGLeG+BPHkTByEk5SWmM3TURCUFZioFRDXgW0qsdVbmK6DyTl3F9S8OIDOKktSBx9Xv29WBBTwGrifrnIJa8cZox1iFBJhqBgXJfyJbMoev85vLIS4k86VcFKROpd1vd3lm8sMbSKrd/rRdzAMfj37KD43X/hS21BbL/h9fp6wUgBqwl7baPHU98Ynhzi0DFJ4aqpM8ZQuXoJRW8/hT9vEzH9hpM07hLdFSgiDaJ9QuDvDcUwqAHumUkcexHunh3seeEBnOR0oo7T8l0/poDVRH1XarjyQ5ezO1hc1knhqqmr3vwNRf/5J1XrvyCqY09Sb3yIyLadGrtZIhJG4iMsmsfAhpL6uZPwf1mWRcq5v8Qt3M3uJ2+n+S//QkSLzAZ57WCgST1NkGcMlyxwifXB4yc7mkDYhPnz88h/9h52PnAdbmkhaVfeTvrP71W4EpFGkZVgsaEeamEdjOWLIO2yW3ES09j9+G9xSwoa7LWbOgWsJuiBVR7zthmeHeqQGq1w1RR5ZSUUvvUEeX+8kqr1X5By7i9p8X+PENN9oAKxiDSaDgmwsYHXZrZj40mfcgempordT9yGV7yMl9oAACAASURBVF3ZsA1oojRE2MSsyDf8ZqnHr3rajGit/NvUmJpqSj/8D8WzXwLPJXHMecQPOxs7SktHiEjjy0qw/r+9+46Oqtz+Bv49M5OpmUkvhJCEQFAgEDoRCAExgkhTgasIIlwpKiIIAtfy2hBBEUGKcC2gFwtIURH1Rw8dQm+KtAQCpJBk0qaf87x/BCIJCUySmZwp+7MWKyvTzmYTmC/7OfMc7Mpy3l5Y1ZEFhiF4zLvIXfgq8r+ZA27Qi/Veg6uhgOVCDDaGYdtsaBkAzOxA4cqVMEGA8WgqCn9dDr7wBjQP9IWuz9OQagPELo0QQsrF6jhcLQXMPINCWr/TdHmjOAQ++xryPn8bMo0/8NTL9Xp8V0MBy4W8ekDApWLgyGOyev+LQapnOncchb98AeuVc1C26oLg8e/TiZyEEJcUqwUYgIxioJl//R9f1aIT/B8bB/26z2Bo1tqrt2+ggOUifs0QsOSMgCVdJWgeQOHKFVivp6Nww1cwnTkIefT9CJk4F4rYeLHLIoSQajW+uRfWxWKGZv7ivJdokgag+NxJFKyaD5+IxvBpECNKHWKjgOUCsg0Mo3fy6BfFYXxzWhoUG1+Yh8Lfv4HhwGZIg8IQ+OzrUCV0o5PXCSEuL1IDyLj626qhKhzHQd7v37DlXUXeV+8h9JVPIVFpRKtHLPRuLjLGGEbt5MFxwJfdaUsGMQkmAwp/+wZZ74+G6eQ++D82DuEz/gt1myT6cyGEuAWphEOMtmyzUTFxPgoEjXoTfLEe+d/OBRPq/8R7sdEES2SLzwj4/QrDb32kCFXRm7gYGG9D6b4/UPTHSghmA7TJj0Hba6hX/o+LEOL+Gms5XBJxgnWLLCQCgcNfRd4Xb6N462qvu2YhBSwRnc5nmHpAwEstJXikEQ0T6xtjDKaT+1D461ew5V6FukMv6PqOhCwgROzSCCGk1mK1HA7kusbESBWfCO3DT6Hot28gj2oG5X3txC6p3lDAEomZZxi23YamOmBOJwpX9c2c/icKf/kClounobi/PQJHvgZ5w1ixyyKEkDqL1QHfXyj7T6QrnN6g6zMclst/I/+b2QidugiygFCxS6oXFd7ZTSYTBg0ahGbNmiEhIQEpKSk4f/48ACAnJwd9+vRBXFwc4uPjsXPnTlEK9hSvpQn4Sw9821MGlUz8vwDewpZ7DXnLZyJ3/mQwkxHBz89CyPj3KVwRQjxGrJZDkRXIN4tdSRlOIkXgiOng5ErkffUemNUidkn14o7RydixY3H27FkcP34cAwcOxHPPPQcAmDFjBhITE3Hu3DksX74cw4YNg9VqrfeCPcHmTAHzTgqY3UmChCAKV/VBMJWWXdpm9lhYMs4iYNhUhE5d6FXjakKId7i1VYMrnId1i1SjQ9DoN2G9ng79us/ELqdeVAhYSqUSffv2LR8pJiYmIj09HQCwevVqjB8/HgDQsWNHREREIDU1tX6r9QA3TGUXck5pyOHleFoadDbGGErTtiBr1nMo3fMrdL2fRvhrX0DT6SFwEqnY5RFCiMPF6sq+iv1JwsrkjeIQMHgCSvf9DsPh7WKX43R3PQdrwYIFGDhwIPLy8mC1WhEeHl5+X0xMDC5fvlztc4uKKv7JKhQKKBSKOpbr3hhjGL+bh5kHViRLIXGBtXFPZsk8D/3aJbBcOgNV22T4DXiOTmAnhHi8AAUHP7m4e2FVR5PYG6Zzx1Dw40LIY5pDFhR+7ye5qWoD1qxZs3D+/Hls3boVRqOxxi/cqFHFS4lMmzYN06dPr3mFHqKgoACrL8uw9pIKyxONUJptLrM+7koKCgrq/BrMUAzr9tWwHd4GLjQSihGvg2vcEkUMQH5+3Yt0AY7okzegPtmH+mQ/d+lVpEqNv/MsyBfpjeaufeo1DDh/EjkrPoBi5JvgJJ6xmhMYGFjh+yoD1ty5c7Fu3Tps2bIFarUaarUaMpkMWVlZ5VOs9PR0REVFVXugK1euQKfTlX/v7ROsqwYOM3arMLwph2db6e79BC9W+YfUXkzgy/az2rgCTBDg99g4+HbrD07qmUuBte2Tt6E+2Yf6ZD936FWsnw3ZVhkCA8Xbz6/6PgXC/MwM5C6aBp8jm6F7+Kl6rau+3BEb582bh++//x6bN2+Gv/8/V4ocMmQIli5dCgBIS0vD1atXkZycXO0L63S6Cr+8OVwJjGHCISV8fYCFXTzzzV5s5ounkTNvIvQ/LoSy1QMIf/1LaJMHeWy4IoSQu4n25ZBR4npLhLcomsRD+9BQFP2xEpaMs2KX4xQVJliZmZmYMmUKYmNj0bNn2RWwFQoFDhw4gDlz5mDEiBGIi4uDXC7HypUr4ePjI0rR7mbJGQE7c2XY9IgU/go678qR+MI8FG74CoZDW+ET1Qwhk+ZDEXO/2GURQoioonyBjBLX2QurKro+w2E6ewT5/5uD0FcXQ6JQiV2SQ1UIWJGRkWCs6sQbFhaGTZs21UtRnuSsnmHaAQHPNbEgJZIuveIozGZFyc6fUfR/34GT+SDgyUlQd3rYY9byCSGkLqJ9OZRYAb0FCHDRBSROKkPgiOnI+ehF6NcvReCTk8UuyaFoJ3cnsgkMz+zg0cgXeCveDIACliOYzh6Bfu1nsOVehW+3ftA9MgIStVbssgghxGVE3/wnMaPEdQMWAPiENIT/4+NR8MN8qJp3hCqhm9glOQwFLCeafUzAoRsMewdIoaZO15ktLwuFP38O44k9kDdphdBn/wN5BO3ATgghlUX7li0LZhQztHHxDa3VnXvDdCYNBasWQB7THFK/ILFLcghaT3GSIzcY3jki4LU2EnQOpTbXBbOYUfTHSmTNHgtzxl8IHDEdIRM+pHBFCCHVCFUBcglw2YVPdL+F4zj4/+tlQCJFwZrF1Z6q5G5oruIEJhvDiO02tAoE3mxL4aq2GGMwndwH/U/LwBfmQdvjcWgffsrjToQkhBBHk3Bc+Ynu7kCq0cF/8IvIX/E+jMd2Qd22u9gl1RkFLCd445CAC8XA4UEyyKWuPZp1VdbsK9Cv+wzms0egbN4RwePfh09opNhlEUKI23D1rRoqU7dJgrF1V+jXLoaiWRtINe69ZySNVxws9XrZhZzf7yBBy0AKVzXFzEbof/kC2R8+D9uN6wh67m0EjX2XwhUhhNRQtBtNsG7xH/wiGM+jcP1SsUupM5pgOVCRheHZHTySwjlMogs51whjDMbD22H66b+A2Qhd72HQ9hwMzkcudmmEEOKWonw5bLwiiF1GjUh1gfAfNBYF38+Dql0PqFp0ErukWqOA5UCv7Odxwwxse1QKqYSmV/ayZF6Aft0SWC6ehrR5J4QMnQBZQKjYZRFCiFuL1nLINpadF6yUuc97krpTCgxHU6Ff/SkUM5ZBonTPLY5ozOIgGzIEfHmWYX6iFI117vODLCbBbIR+/TLkfPwShNJiBL/wARRDJlG4IoQQB4j2Lft62c2WCTmOQ8DQiRCMpSj85Suxy6k1mmA5QK6R4bldPPpFcRh9H4UrexhPH4B+zWIIJYXw6zcKvj0eAyeVwZCfL3ZphBDiEW7thXW5lKGZv3u9N8kCw+DXbxT0a5dA1bY7lHEJYpdUYzTBqiPGGMbv5sELwOdJUpe95pOr4AvzkLd8JvI+fwuysEYIm74U2l5DwEkp6xNCiCNFagAOQEax2JXUjqZrP8hjW6Jg1XwIFpPY5dQYBaw6WnmeYV06w7IkKcLVFK6qwwQBJXs2IuuDMTBfOIXAEdMRPG4mZMENxC6NEEI8klzKoYEabrVVw+04iQQB/5oEvuAGiresFrucGqOxQR1cKWGYsIfH8KYcnmhMWbU61uvpKFj9KSyXzkCd2Bv+/Z+DREPXDiSEEGdzt72wKvMJawTtg0+geNuP0HR6CLLgCLFLshulgloSGMOoVB5aObCwi1TsclwSs5hRuHEFsj96EUJpEUJe+giBT06mcEUIIfUkWut+J7lXpn3oSUh9/aFfv0zsUmqEJli1tPi0gK3XGDY9IoW/gpYGKzP9fRT61QthK8iF7uGnoH1oKDgZ7WlFCCH1KUrD4UCOe+2FVZlEoYTfY+OQv3wmjKcPQNWys9gl2YUCVi38pWeYdlDAhBYSpETSEPB2fEkhCn/+HIa0LZA3aYWwMe/AJ6yR2GURQohXitYCV0oAXmBuvT+jqnVXKJq1hX7dUiibtXWLTagpHdSQTWB4ZgePKF9gTmdq3y2MMZQe3IzsD8bAeHo/Ap6cjJAJH1K4IoQQEUVpONgYkON+H8KrgOM4+D/xAnh9Loq3/Sh2OXahCVYNfXBMwOEbDHsHSKF2o51xncmaexX61QthPncM6vY94TdoHKRaf7HLIoQQr9dQU/Y+lVnK0MDNP+nuE9YIvsmPoWjLKqg79IIsKFzsku6KRjA1cDiX4d0jAl5rI0HnUGods1lRtOk7ZM8ZD1t+FoLHzUTgiOkUrgghxEVE3rzKTKabn+h+i673MEjVOuh//q/YpdwTTbDsZLQxjNhhQ6tA4M22FK7MF0+jYPUC2HIyoe05GNrewyCRK8UuixBCyG2ClYBcUjbB8gQShQp+A8cg/5sPYPrzEJTNO4hdUrUoKdjpjUMCLhYD/+shg1zq3mPWuhAMJShYtQC5n06BRKFG6NRF8Os/msIVIYS4II7jEKkBMkvFrsRxVG27QxGXAP26z8BsFrHLqRYFLDvsuCbgk5MC3u8gQctA7wxXjDEYjqQi64MxMBxJhf8TLyDk5Y8hj4gVuzRCCCF3EanhPGaCBdw84f3x52G7cR0luzeKXU61aInwHoosDM+m8kgK5zAp3jvzqC0/G/o1i2A6kwZV667wf/x5SP2DxS6LEEKIHTxtggUAPg1ioEnsjeJN30HTKQUSta/YJd3BOxNDDUzexyPPDKxIlrr1HiK1wXgexdvXInv2WFivXULQc28haPSbFK4IIcSNeNoE6xZdn+FgNguKt7rmdQppgnUXv2QI+Opvhi+SpGis865wZbn8NwpWL4D16kX4Jg2Aru9ISJRqscsihBBSQ7cmWIwxcJznvJdJ/YLg23MwireuhqZbP8gCQsUuqQKaYFUj18gwZhePflEcRt/nOT+Q9yKYDNCvW4qcTyYBDAidPB/+jz9P4YoQQtxUpIaDRQBuuPlmo1XR9nwCEqUGRb99I3Ypd6AJVhUYYxi3mwcvAJ8nST0q8d+N6c9DKFi1AIKhCH79R8M3+TFwUrqQNSGEuLPIm6cnZZYCISpxa3E0iVINXZ/h0K9dDN8ej0Pe0HU+eEUTrCqsPM+wPp1hWZIU4W6+8609BGMp8n/4BDeWvQFZWCOETV8G7YODKVwRQogHiLy5m/tVDzwPCwA0D/SBLDgChRu+FLuUCmiCVcmVEoYJe3gMb8rhicaenz+NZw5Cv+pTCCYDAv71MtSJfbxmYkcIId4gVAnIOM/ZbLQyTiqDX//RyPvqPZjOHoHyvnZilwSAAlYFAmMYlcpDKwcWdvHs6Y1gKIb+p//CcHAzFPe3R8C/Xna5EwQJIYTUnVTCoYHa87ZquJ2yVRfIG7dA4S9fQjGlDTiJ+AMS8StwIYtPC9h6jWF5dyn8FZ47xTGePoCsOeNhPLEHAU9ORvC4mRSuCCHEg3nqVg23cBwHvwHPwXr1AgxHtotdDgCaYJX7S88w7aCACS0kSIn0zNwpGIqhX78MhrQtULboCP+hEyHzDxG7LEIIIU7miZuNVqZo3AKq1l1RtPFrqBOSwPnIRa3HM5NEDdkEhmd28IjyBeZ09syWGE/tQ9bscTCe3IeAYVMQNOZdCleEEOIlPH2CdYvu0WfB62+gdP8fYpdCEywA+OCYgCM3GPYOkEIt86ylQb60CIXrPoPh8HYoW3RCwNCJtBM7IYR4GU/dbLQyn7BGUHd4EEVbVkGT2EfUKZbXB6yT+QzvHRUwPUGCTqGeNb0yntiLgh8XgtmsCHh6KtQdenn0XyxCCCFVi9RwKLUBhRbAXyF2Nc6lffgpGA5tQ+n+P+CbNEC0Orw6YNmEsk8NxumA/9fOc8IVX1II/brPYDyyA8r4RAQMeQlSvyCxyyKEECKS2zcb9fSA5RPS0CWmWF4dsD46IeBoHsP+gVIopJ4x2TEc3w39j4sAgUfgiOlQtetBUytCCPFytzYbzSxliA/0/PcEV5hieW3AOp3P8PZhAVNbSdAxxP2nV3yJHvo1S2A8thPKVl0QMGQCpLpAscsihBDiAhqoAQ6e/0nCW1xhiuWVAcsmMIzeySNWB7zT3v3DleHYTujXLAYYQ+AzM6Bqm0xTK0IIIeV8JBzC1Z67m3tVxJ5ieWXA+uSkgLRchj0DpFC68acG+WI99GsWwXh8N1Stu8J/yARItQFil0UIIcQFNVR7x1YNt/iENIS6fU/RplheF7D+0jO8eVjA5FYSPBDmntMrxhiMR3dCv3YxAA6BI1+Dqk0STa0IIYRUK0IDXDeIXUX90j78FAyHt4syxfKqgMULDKNTeURpgPc6uGe44ovyUbBmEUwn9kLVpjv8B78Aqa+/2GURQghxcRFqDvtzBLHLqFc+oZGiTbG8KmB9elrA/hyGnf3db0NRxhiMR3ZAv3YJIJEg8NnXoW6TJHZZhBBC3ESEGrjmZRMsQLwpltcErHOFDK+lCXippQTdwt1resUX5qHgx0UwndoHVdtk+D/xAqS+fmKXRQghxI00UHPINQJWgcFH4l5DhroQa4rlXkmjlgTG8O+dPCLUwKyO7vVbNhzfjew542FJ/xNBo95A0Mj/ULgihBBSYxFqgAHI9tIpllCUj9K0LfV2TK+YYC0+LWBXFsP2R6XQ+LhHaheMpdCv+wyGtC1QJXSD/5CXKFgRQgiptYibm41eMzBE+rrHe6Gj+IRGQtWqC0q2ry2bYkmcP2xxr3FOLVwsYpiRJuCFFhL0iHCP3675/Alkf/g8jCf3IuDpqQh89nUKV4QQQuokQl321RvPwwIA355PwJZ7FaZT++vleB49wbq1NBiiBOZ0cv1wxWwWFG78GiU71kEeG4+Qpz+CLDBM7LIIIYR4gGAlIOOA6wbv2QvrdorGLSBv3ALF29dA1bqL049XIXVMnDgRMTEx4DgOx44dK789JycHffr0QVxcHOLj47Fz506nF+YIy/4UsOM6w5fdpfB18aVBy7WLyPl4Ikp2/gK//v9GyIuzKVwRQghxGAlXtpu7t06wAED74BBYLp2B+dIZpx+rQsAaPHgwdu/ejejo6AoPmjFjBhITE3Hu3DksX74cw4YNg9VqdXpxdZFezDDtoICx90vQq6HrTq+YwKN424/I+fhlAEDolAXQPjgYnEQqcmWEEEI8TYSawzUv2s29MmXLzpCFRqJ4+xqnH6vCEmH37t2rfNDq1atx/vx5AEDHjh0RERGB1NRUPPTQQ04vsDYYYxizi0eAHPios+uGK1teFvK/+xiWi6fg2+Nx+PUdKcoFKQkhhHiHCDVw3Sh2FeLhJBL49nwC+tWfwpqTCZ/QSKcd657pIy8vD1arFeHh4eW3xcTE4PLly3d9XlFRUYVfZrO57tXa6YuzDFuuMnyeJIVO7npLg4wxlB7cguwPXwCfn43gF2bDf+AYCleEEEKcqoGXT7AAQNOhFyS+/ijZsc6px3HaSe6NGjWq8P20adMwffp0Zx2uXKaBwyv7NHg6xoqOGjPy851+SLsUFBQAAJihCJaNX4H/8yCkrZMg7zMSBqUaBlcpVGS3+kTujvpkH+qTfahP9nP3Xvlzclwt9UG+k99zXL1P0g4pKN25HsID/cFpHPMp/cDAwArf3zNgBQUFQSaTISsrq3yKlZ6ejqioqLs+78qVK9DpdOXfKxQKKBSK2tRsN8YYhh3goZMzLOquhr9C49Tj1ZQq6wIKfpgH2Gx0qZu7qPxDSqpGfbIP9ck+1Cf7uXOvmgYLuHGGh69fAORS567wuHKfhIeG4PqeXyA7tRt+j4xwyjHsOkFpyJAhWLp0KQAgLS0NV69eRXJy8l2fo9PpKvxydrgCgBV/M/xfJsN/k6TwV7jO0qBgNsHy23Lk/fdN+EQ0Qdj0pRSuCCGE1LsGN/fCyvbi87AAQKLRQpPYG6W7N0CwmJxzjNu/GTduHCIjI5GZmYnevXujadOmAIA5c+Zg7969iIuLw7PPPouVK1fCx8fHKQXV1tVShsn7eTwTx+HRKNc5sd2ScRY5c1+E7Vgq/AdPQPC49yD1CxK7LEIIIV4oQv3Pbu7ezjf5MQiGEhgObHLK61dYIly2bFmVDwoLC8OmTc4pwBEYYxi3i4dKCnyS6BrbGzDehuLNP6Bo03fwiWwK5ZDJ8G0WL3ZZhBBCvFi4quyrt0+wAEAWFA5VmyQU71gPTddHHb49kuuMeupg5XmGjVcYliVJEagUf2nQmpOJnAVTULTpO2hTnkLoy/MgCY4QuyxCCCFeLlgJSDggy4s3G72d9sHB4POuO+XyOW5/qZzrBoaX9/EY1oTDgGhx8yJjDKV7NqLw588h9Q9GyMR5UMTcL2pNhBBCyC1SCYdQpfdeLqcyeaM4yKPvR8nuX6Fq3dWhr+3WAYsxhud38/CRAJ92EXdpkC/MQ8EP82H6Mw2aLo/Cb+AYSBRKUWsihBBCKgtXA1m0RFhOk9QfBSs/gjX7CnzCGt37CXZy6yXCHy4w/JzBsKSrFEEiLg0aju9G9ofPw5J5HkFj30XA0JcoXBFCCHFJ4SoOWTTBKqdOSIJE44fSPRsd+rpuG7CyDQwv7eUxNJbDE43F+W0IxlLkfzsX+ctnQt4kHmHTl0LVopMotRBCCCH2oAlWRZyPvGzLhoObIZgdt2WD2wasCXt5cBywSKSlQfOFk8j+8HkYT+xFwLApCBr1JqS+jtkNlhBCCHGWBmqaYFWm6dIXzGyA4ch2h72mW56D9eNFAWsuMfzwoBQhqvpdGmQ2Cwp/+wYl29dC3rglQiZ8CFlQ+L2fSAghhLiAcFXZBIsxBo4T/5P3rkAWFA5li04o3bUBmsQ+DumL202wco0ML+7h8XgMh6Gx9fuDYb12CTnzXkZJ6k/w6z8aIRPmULgihBDiVsJVHEw8UGQVuxLX4tutP6zXLsKS/qdDXs/tJlgT9/HgGbCkq7TekjcTBJSkrkfhrysgC22I0Fc+hbxhbL0cmxBCCHGk8JuXy8kyAH5ycWtxJYr72kEa3AAluzdA0bhFnV/PrSZY6y8J+OECw6ddpAhT10+44ovycWPp6yj85Qv4dh+AMApXhBBC3Fj4zVNrsox0HtbtOIkEvl37wXhsF/hifZ1fz20CVp6J4fk9PAZEcxjWpH7ClensEWR/+AKs19MRPP59+A8cA86H4j4hhBD3dfsEi1Sk6fQwIJGgdP8fdX4ttwlYk/bxMPPA0m7OXxpkvA2Fvy7HjaWvw6dhLMKmLYHyvnZOPSYhhBBSH7Q+gEpKE6yqSDRaqNv2QOmejWACX6fXcotzsDZkCFh5nmFFshQNnLw0aMvPRv7/5sCS8Rd0j46C9sHB4CRuk0MJIYSQu+I4rmwvLJpgVck3qT8MBzfBdPogVK0eqPXruHzAKjAzjNvNo28jDs/EOTdcGU/sQf73n0CiVCPkpbkOOcmNEEIIcTXhKo4mWNWQN4qDT9R9KNm9oU4By+VHM6/s51FqBZY5cWmQWS0oWLMYeV+9B2VcAsJeXUzhihBCiMcKVwPXaYJVLd9u/WE+ewTW3Ku1fg2XDli/XxGw4m+GeYlSRPo6J1xZczKRM38ySvf/Af/BLyJw1BuQqLVOORYhhBDiCsJVHLJpglUtdZskcEoNDAc31/o1XDZgFVoYxuzi8XBDDqPvc064Kk3bgpy5E8AsJoROmg/fbv1pV1tCCCEeL1QF5ND1CKvFyRVQt+sBw8EttT7Z3WUD1tT9PIoswOfdHb80KJiNyP92Lgq+nQtVQjeETl0EeWQThx6DEEIIcVVhNwOWwGiKVR11pxTwhTdgPnu0Vs93yZPcN2UK+OIsw9JuEkQ5eGnQcvUi8r+eBV5/AwFPT4Wm40MOfX1CCCHE1YWqONgYoDcDgUqxq3FN8uj7IAuLQunBzVA271Dj57vcBKv45tLggxEcxt7vuPIYYyjZvQE5n7wMTiZH6JSFFK4IIYR4pTBV2ddsWiasFsdx0HROgfHkXgiG4ho/3+UC1rSDAvJMwBdJjlsaFAzFyF8+E/o1i6F54BGETp4Pn7BGDnltQgghxN2EKsveX3NMtER4N+oOvQCBh+FIao2f61JLhNuuClj6p4BFXSRorHNMuDJfOoP8b2ZDMBkQNPpNqFp3dcjrEkIIIe4q7OblcrJpq4a7kuoCoWzeEaUHN8G3W78aPddlJlglVoZ/7+SR3IDD8y3qXhYTBBRtWYXchVMh9Q9G2KuLKVwRQgghAHQ+gFxCEyx7qDulwHr5b1ivp9foeS4zwfrPQQHZRmDLo1JI6rg0yBcXIH/lRzD/fRTaXkOhe2QEOKnL/FYJIYQQUXEchzAVnYNlD1XLzpBodCg9uBn+A8fY/TyXmGClXhew6IyADzpJ0KSOS4Omv48i+6MXYL16EcHj34dfv1EUrgghhJBKQlUc7YVlB07mA3X7njAc2gbG2+x+nugBy2ArWxrsGsbhpZa1L4fxPAo3rsCNz16DT3gMwqYtgfK+dg6slBBCCPEcZRMsWiK0h7rTwxCKC2D685DdzxF9tPN6moCrpcBvvWu/NGgryEH+N7NhyfgLur4joe01FJxE9OxICCGEuKxQFXBWL3YV7kEe2QQ+EbEoPbgJqvhEu54jagrZkyVgwSkBMztI0My/duHKeHIfsj96AXxBLkImfARdypMUrgghhJB7CFXS9QhrQt35YZhOHQBfYl8qFS2JGG0Mo3fy6BzKYVJ8zctgNgv0a5cg78t3oGjSGmGvLoEitqUTKiWEEEI8T5gKyDGJXYX7ULfvCXAcDId32PV40ZYI/99hARklwE8pUkglNZteWXOvIv/rNZ0q+QAAChVJREFUWbBevwz/J16Ahi7STAghhNRIqIpDibXsXGi1jN5D70Xq6wdVy84wHNgEbfKgez5elAnW/mwB804KeKedBM0DavaHWnpoK3LmTgAzmxA6+RP4Jg2gcEUIIYTU0K3L5dAnCe2n7vwwrNcuwpJ54Z6PrfcJlsnGMGonj/bBHKa0tj/fCWYT9GsXw3BwM9QdesF/8IuQKNVOrJQQQgjxXKGqsuFEtpEhRkuDCnso728PicYPhsPbII9sctfH1nvAeueIgAtFwJHHpJDZuTRouXYR+Ss+AK/PQcCwKdB0SnFylYQQQohnowlWzXFSGVRtu8N4JBV+/UeDk0irfWy9LhEeyhXw0QkBb7WTID7w3uGKMYaSPRuRM+9lcDIZQqcsonBFCCGEOECIEni6KYdmfjS9qgl1+57gC2/AfOHUXR9XbxMsM88wKpVH60BgWsK9c51gKEHBqvkwHt8NTbd+8B84FpyPvB4qJYQQQjyfVMJhZU/Rt8N0O/KY5pAGhcNweBuUcQnVPq7eJlgzjwr4Sw8sT5bB5x5Lg+b0v5A990WYzh5F4Kg3EDB4AoUrQgghhIiO4zio2/WA8dhuMJul2sfVS8A6eoPhg2MC3mgrQUJQ9eGKCQKKt/2I3E+nQKoNQNiri6FO6FYfJRJCCCGE2EXdvieYqRSmvw5X+xinzwYtPMOoVBtaBgD/aVN9nuOL9cj/di7Mfx2CttdQ6Po+QxdpJoQQQojL8QmPhk+DGBiOpEIV/0CVj3F6gvngmIBTBcDBQTLIpVVPr0x/H0P+yg8BgUfwuJlQNu/g7LIIIYQQQmpN1a4Hijd/D8FsgkShvON+py4RnshjmHlUwIwECdoF3xmuGM+j8LevceOz/8AnPAphry6hcEUIIYQQl6dumwxmMcN05mCV9zttgmUVGEbttOE+f+DNdnfmOJs+F/nfzIEl/Qx0jzwD7UND77qfBCGEEEKIq5AFN4BP1H0wHN0Bddvud97vrAPPPyngWB6wf6AUikpLg8ZT+1Hw3cfg5EqETPgQith4Z5VBCCGEEOIU6rbdUbhxBQRTKSRKTYX7nLZEOOe4gFdbS9Ax5J9DMJsF+vXLkPfF25DHtkTYq0soXBFCCCHELanaJAE2K0ynDtxxn9MCVowWePu2pUFb7jXkzH8FJbt/hd9j4xH077cg0WiddXiXYjabMWfOHJjNZrFLcWnUJ/tQn+xDfbIP9cl+1Cv7eFOfZAGhkEffD8OxXXfcxzHGmCMPVlRUBD8/P2w5V4BeTf0BAIbD21GweiGkWn8EjvwP5I3iHHlIl3erJ4WFhdDpdGKX47KoT/ahPtmH+mQf6pP9qFf28bY+FW9fi8KNKxA5d0OF2502weoYKoFgNiH/+3nI/98cqOI7I3TqIq8LV4QQQgjxXLeWCStz3qcIr6cjZ90i8AXZCHjqFag7pYDj6IKShBBCCPEct5YJ77jd0Qe6teJ48ZMpCGjQCAFjZoEPa4Ti4mJHH8ptFBUVVfhKqkZ9sg/1yT7UJ/tQn+xHvbKPN/ZJ2nc0ioqKoNVqy4dJDj8HKzMzE40aNXLkSxJCCCGEuLzbzztzeMASBAHXrl2rkOIIIYQQQjydUydYhBBCCCHezqnXIiSEEEII8UYUsAghhBBCHIwCloOZTCYMGjQIzZo1Q0JCAlJSUnD+/HkAQE5ODvr06YO4uDjEx8dj586dIlfrGpYvXw6O4/DTTz8BoD5VZjabMWHCBMTFxaFVq1YYPnw4AOpTZb/99hvatWuHNm3aID4+Hl9//TUA6tPEiRMRExMDjuNw7Nix8tvv1heDwYCnnnoKTZs2RbNmzbBmzRoxSq9X1fVp1KhR5f+ed+3aFWlpaeX3UZ+O3XH/tm3bIJVKMX/+/PLbvLFPAABGHMpoNLKNGzcyQRAYY4wtXLiQJScnM8YYGzVqFHvrrbcYY4wdPHiQNWzYkFksFpEqdQ2XLl1iDzzwAEtMTGTr169njFGfKps0aRKbMGFC+c/U9evXGWPUp9sJgsACAgLY8ePHGWNlP1cKhYIVFRV5fZ9SU1PZlStXWHR0NDt69Gj57XfryzvvvMNGjhzJGGPs4sWLLCQkhN24caO+S69X1fXp559/ZlarlTHG2IYNG1h0dHT5fdSnoxXu0+v1rGPHjqxfv37sk08+Kb/dG/vEGGMUsJwsLS2t/C+kRqMpf3NkjLGOHTuyzZs3i1SZ+HieZ7169WKHDh1iycnJ5QGL+vSPkpISptVqWWFh4R33UZ/+IQgCCwwMZKmpqYwxxo4fP84iIiKY2WymPt1U+Q3xbn1p0aIF27dvX/l9Q4YMYZ9//nn9FSuiqoLDLbm5uUwmk5UHLupTxT4NHz6c/fzzz2zkyJEVApa39omWCJ1swYIFGDhwIPLy8mC1WhEeHl5+X0xMDC5fvixideKaN28eunbtivbt25ffRn2q6MKFCwgMDMSsWbPQoUMHJCUlYevWrdSnSjiOw6pVq/D4448jOjoa3bp1w9dff43i4mLqUxXu9fNz+fJlREdHV3mfN1uwYAH69u0Lmaxsj27q0z/WrFkDiUSCAQMG3HGft/bJaZfKIcCsWbNw/vx5bN26FUajUexyXMqpU6ewdu1arzsfpqZsNhsyMjLQokULzJ49G0ePHkVKSgpOnz4tdmkuxWazYebMmVi3bh26d++OtLQ0DBgwoMpzRAipjZUrV2L16tX0b1YVsrKyMHPmTOzYsUPsUlwKTbCcZO7cuVi3bh1+//13qNVqBAUFQSaTISsrq/wx6enpiIqKErFK8ezatQvp6emIi4tDTEwM9u/fj7Fjx2L16tXUp9tERUVBIpHg6aefBgC0bdsWjRs3xsmTJ6lPtzl27BiuXbuG7t27AwA6duyIyMhInDhxgvpUhXv9exQVFYWMjIwq7/NGq1atwjvvvIPNmzcjLCys/HbqU5nDhw/j+vXraNOmDWJiYrBmzRq8++67eP311wF4cZ/EXqP0RB9//DFr164dy8/Pr3D7yJEjK5xUGhER4VUn297N7edgUZ8qSklJYRs3bmSMlZ0gGhQUxDIzM6lPt8nKymK+vr7szJkzjDHGzp07xwICAlhGRgb16abK58zcrS9vvfXWHScl5+bm1nfJoqjcp1WrVrGmTZuy9PT0Ox5Lfar6XLXK52B5a58oYDnYlStXGAAWGxvLEhISWEJCAuvUqRNjrOxNICUlhTVt2pS1aNGCbdu2TeRqXcftAYv6VNGFCxdYjx49WHx8PGvdujVbs2YNY4z6VNl3331X3qP4+Hj27bffMsaoT2PHjmUNGzZkUqmUhYaGsiZNmjDG7t6XkpISNnToUBYbG8vi4uLYqlWrxCq/3lTXJ5lMxiIjI8v/PU9ISCj/BBz16Z8+3a5ywPLGPjHGGF0qhxBCCCHEwegcLEIIIYQQB6OARQghhBDiYBSwCCGEEEIc7P8D4kZN+RZRbA0AAAAASUVORK5CYII="},"metadata":{"image/png":{"height":480,"width":600}},"execution_count":1}],"cell_type":"code","source":["plot(x -> flight(x, 45), 0, howfar(45)) \nplot!(x -> flight(x, tstar), 0, howfar(tstar))"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

Potential issues

","metadata":{"internals":{"slide_type":"subslide","slide_helper":"subslide_end"},"slideshow":{"slide_type":"slide"},"slide_helper":"slide_end"}}, -{"cell_type":"markdown","source":"

The higher-order methods are basically various derivative-free versions of Newton's method (which has update step $x - f(x)/f'(x)$). For example, Steffensen's method (Order2()) essentially replaces $f'(x)$ with $(f(x + f(x)) - f(x))/f(x)$. This is a forward-difference approximation to the derivative with \"$h$\" being $f(x)$, which presumably is close to $0$ already. The methods with higher order combine this with different secant line approaches that minimize the number of function calls. These higher-order methods can be susceptible to some of the usual issues found with Newton's method: poor initial guess, small first derivative, or large second derivative near the zero.

","metadata":{}}, -{"cell_type":"markdown","source":"

When the first derivative is near $0$, the value of the next step can be quite different, as the next step generally tracks the intersection point of the tangent line. We see that starting at a $\\pi/2$ causes this search to be problematic:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["Roots.ConvergenceFailed(\"Stopped at: xn = 1.7282686480730119e9\")\n"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["find_zero(sin, pi/2, Order1())"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

(Whereas, starting at pi/2 + 0.3–where the slope of the tangent is sufficiently close to point towards $\\pi$–will find convergence at $\\pi$.)

","metadata":{}}, -{"cell_type":"markdown","source":"

For a classic example where a large second derivative is the issue, we have $f(x) = x^{1/3}$:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["Roots.ConvergenceFailed(\"Stopped at: xn = -2.1990233589964556e12\")\n"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["f(x) = cbrt(x)\nx = find_zero(f, 1, Order2())\t# all of 2, 5, 8, and 16 fail or diverge towards infinity"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

However, the default finds the root here, as a bracket is identified:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["(0.0, 0.0)"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["x = find_zero(f, 1)\nx, f(x)"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

Finally, for many functions, all of these methods need a good initial guess. For example, the polynomial function $f(x) = x^5 - x - 1$ has its one zero near $1.16$. If we start far from it, convergence may happen, but it isn't guaranteed:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["1.1673039782614185"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["f(x) = x^5 - x - 1\nx0 = 0.1\nfind_zero(f, x0)"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

Whereas,

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["Roots.ConvergenceFailed(\"Stopped at: xn = -0.7503218333241642\")\n"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["find_zero(f, x0, Order2())"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

A graph shows the issue. We have overlayed 15 steps of Newton's method, the other algorithms being somewhat similar:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":"Plot(...)","image/png":"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"},"metadata":{"image/png":{"height":480,"width":600}},"execution_count":1}],"cell_type":"code","source":[""],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

Though 15 steps are shown, only a few are discernible, as the function's relative maximum causes a trap for this algorithm. Starting to the right of the relative minimum–nearer the zero–would avoid this trap. The default method employs a trick to bounce out of such traps, though it doesn't always work.

","metadata":{}}, -{"cell_type":"markdown","source":"

Tolerances

","metadata":{"internals":{"slide_type":"subslide"},"slideshow":{"slide_type":"subslide"},"slide_helper":"slide_end"}}, -{"cell_type":"markdown","source":"

Mathematically solving for a zero of a nonlinear function may be impossible, so numeric methods are utilized. However, using floating point numbers to approximate the real numbers leads to some nuances.

","metadata":{}}, -{"cell_type":"markdown","source":"

For example, consider the polynomial $f(x) = (3x-1)^5$ with one zero at $1/3$ and its equivalent expression $f1(x) = -1 + 15\\cdot x - 90\\cdot x^2 + 270\\cdot x^3 - 405\\cdot x^4 + 243\\cdot x^5$. Mathematically these are the same, however not so when evaluated in floating point. Here we look at the 21 floating point numbers near $1/3$:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["1.887379141862766e-15"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["f(x) = (3x-1)^5\nf1(x) = -1 + 15*x - 90*x^2 + 270*x^3 - 405*x^4 + 243*x^5\nns = [1/3];\nu=1/3; for i in 1:10 (u=nextfloat(u);push!(ns, u)) end\nu=1/3; for i in 1:10 (u=prevfloat(u);push!(ns, u)) end\nsort!(ns)\n\nmaximum(abs.(f.(ns) - f1.(ns)))"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

We see the function values are close for each point, as the maximum difference is like $10^{15}$. This is roughly as expected, where even one addition may introduce a relative error as big as $2\\cdot 10^{-16}$ and here there are several such.

","metadata":{}}, -{"cell_type":"markdown","source":"

Generally this is not even a thought, as the differences are generally negligible, but when we want to identify if a value is zero, these small differences might matter. Here we look at the signs of the function values:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["21×3 Array{Float64,2}:\n -5.55112e-16 -1.0 -1.0\n -4.996e-16 -1.0 -1.0\n -4.44089e-16 -1.0 -1.0\n -3.88578e-16 -1.0 1.0\n -3.33067e-16 -1.0 1.0\n -2.77556e-16 -1.0 1.0\n -2.22045e-16 -1.0 -1.0\n -1.66533e-16 -1.0 -1.0\n -1.11022e-16 -1.0 1.0\n -5.55112e-17 -1.0 1.0\n 0.0 0.0 1.0\n 5.55112e-17 0.0 1.0\n 1.11022e-16 1.0 1.0\n 1.66533e-16 1.0 1.0\n 2.22045e-16 1.0 -1.0\n 2.77556e-16 1.0 -1.0\n 3.33067e-16 1.0 1.0\n 3.88578e-16 1.0 1.0\n 4.44089e-16 1.0 1.0\n 4.996e-16 1.0 1.0\n 5.55112e-16 1.0 0.0"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["fs = sign.(f.(ns))\nf1s = sign.(f1.(ns))\n[ns-1/3 fs f1s]"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

Parsing this shows a few surprises. First, there are two zeros of f(x) identified–not just one as expected mathematically–the floating point value of 1/3 and the next largest floating point number. For f1(x) there is only one zero, but it isn't the floating point value for 1/3 but rather 10 floating point numbers away. Further, there are 5 sign changes of the function values. There is no guarantee that a zero will be present, but for a mathematical function that changes sign, there will be at least one sign change.

","metadata":{}}, -{"cell_type":"markdown","source":"

With this in mind, an exact zero of f would be either where iszero(f(x)) is true or where the function has a sign change (either f(x)*f(prevfloat(x))<0 or f(x)*f(nextfloat(x)) < 0).

","metadata":{}}, -{"cell_type":"markdown","source":"

As mentioned, the default Bisection() method of find_zero identifies such zeros for f provided an initial bracketing interval is specified when Float64 numbers are used. However, if a mathematical function does not cross the $x$ axis at a zero, then there is no guarantee the floating point values will satisfy either of these conditions.

","metadata":{}}, -{"cell_type":"markdown","source":"

Now consider the function f(x) = exp(x)-x^4. The valuex=8.613169456441398 is a zero in this sense, as there is a change of sign:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["(-1.0, -1.0, 1.0)"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["f(x) = exp(x) - x^4\nF(x) = sign(f(x))\nx=8.613169456441398\nF(prevfloat(x)), F(x), F(nextfloat(x))"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

However, the value of f(x) is not as small as one might initially expect for a zero:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["-2.7284841053187847e-12"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["f(x)"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

The value x is an approximation to the actual mathematical zero, call it $x$. There is a difference between $f(x)$ (the mathematical answer) and f(x) (the floating point answer). Roughly speaking we expect f(x) to be about $f(x) + f'(x)\\cdot \\delta$, where $\\delta$ is the difference between x and $x$. This will be on the scale of abs(x) * eps(), so all told we expect an answer to be in the range of $0$ plus or minus this value:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["5.637565490466956e-12"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["fp(x) = exp(x) - 4x^3 # the derivative\nfp(x) * abs(x) * eps()"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

which is about what we see.

","metadata":{}}, -{"cell_type":"markdown","source":"

Bisection can be a slower method than others. For floating point values, Bisection() takes no more than 64 steps, but other methods may be able to converge to a zero in 4-5 steps (assuming good starting values are specified).

","metadata":{}}, -{"cell_type":"markdown","source":"

When fewer function calls are desirable, then checking for an approximate zero may be preferred over assessing if a sign change occurs, as generally that will take two additional function calls per step. Besides, a sign change isn't guaranteed for all zeros. An approximate zero would be one where $f(x) \\approx 0$.

","metadata":{}}, -{"cell_type":"markdown","source":"

By the above, we see that we must consider an appropriate tolerance. The first example shows differences in floating point evaluations from the mathematical ones might introduce errors on the scale of eps regardless of the size of x. As seen in the second example, the difference between the floating point approximation to the zero and the zero introduces a potential error proportional to the size of x. So a tolerance might consider both types of errors. An absolute tolerance is used as well as a relative tolerance, so a check might look like:

","metadata":{}}, -{"outputs":[],"cell_type":"code","source":["abs(f(x)) < max(atol, abs(x) * rtol)"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

This is different from Julia's isapprox(f(x), 0.0), as that would use abs(f(x)) as the multiplier, which renders a relative tolerance useless for this question.

","metadata":{}}, -{"cell_type":"markdown","source":"

One issue with relative tolerances is that for functions with sublinear growth, extremely large values will be considered zeros. Returning to an earlier example, we have a misidentified zero:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["2.0998366730115564e23"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["find_zero(cbrt, 1, Order8())"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

For Order8, the algorithm rapidly marches off towards infinity so the relative tolerance $\\approx |x| \\cdot \\epsilon$ used to check if $f(x) \\approx 0$ is large compared to the far-from zero $f(x)$.

","metadata":{}}, -{"cell_type":"markdown","source":"

Either the users must be educated about this possibility, or the relative tolerance should be set to $0$. In that case, the absolute tolerance must be relatively generous. A conservative choice of absolute tolerance might be sqrt(eps()), or about 1e-8, essentially the one made in SciPy.

","metadata":{}}, -{"cell_type":"markdown","source":"

This is not the choice made in Roots. The fact that bisection can produce zeros as exact as possible, and the fact that the error in function evaluation, $f'(x)|x|\\epsilon$, is not typically on the scale of 1e-8, leads to a desire for more precision, if available.

","metadata":{}}, -{"cell_type":"markdown","source":"

In Roots, the faster algorithms use a check on both the size of f(xn) and the size of the difference between the last two xn values. The check on f(xn) is done with a tight tolerance, as is the check on $x_n \\approx x_{n-1}$. If the function values get close to zero, an approximate zero is declared. Further, if the $x$ values get close to each other and the function value is close to zero with a relaxed tolerance, then an approximate zero is declared. In practice this seems to work reasonably well. The relaxed tolerance uses the cube root of the absolute and relative tolerances.

","metadata":{}}, -{"cell_type":"markdown","source":"

Searching for all zeros in an interval

","metadata":{"internals":{"slide_type":"subslide","slide_helper":"subslide_end"},"slideshow":{"slide_type":"slide"},"slide_helper":"slide_end"}}, -{"cell_type":"markdown","source":"

The methods described above are used to identify one of possibly several zeros. The find_zeros function searches the interval $(a,b)$ for all zeros of a function $f$. It is straightforward to use:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["3-element Array{Float64,1}:\n -0.815553\n 1.42961 \n 8.61317 "]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["f(x) = exp(x) - x^4\na, b = -10, 10\nzs = find_zeros(f, a, b)"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

The search interval, $(a,b)$, is specified through two arguments. It is assumed that neither endpoint is a zero. Here we see the result of the search graphically:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":"Plot(...)","image/png":"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"},"metadata":{"image/png":{"height":480,"width":600}},"execution_count":1}],"cell_type":"code","source":["plot(f, a, b)\nscatter!(zs, f.(zs))"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

We can identify points where the first and second derivative is zero. We use D from above:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":"Plot(...)","image/png":"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"},"metadata":{"image/png":{"height":480,"width":600}},"execution_count":1}],"cell_type":"code","source":["f(x) = cos(x) + cos(2x)\na, b = -10, 10\ncps = find_zeros(D(f), a, b)\nips = find_zeros(D(f,2), a, b)\nplot(f, a, b)\nscatter!(cps, f.(cps))\nscatter!(ips, f.(ips), markercolor = :yellow)"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

The find_zeros algorithm will use bisection when a bracket is identified. This method will identify jumps, so areas where the derivative changes sign (and not necessarily a zero of the derivative) will typically be identified:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":"Plot(...)","image/png":"iVBORw0KGgoAAAANSUhEUgAAAlgAAAGQCAYAAAByNR6YAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAAPYQAAD2EBqD+naQAAIABJREFUeJzs3Xl8VNX9//HXuXdCQkISCBC2BBAQENkXZZFNZXdBtKLW+nW3dW21Qlsr1qXab93qt9Xqr1Ztq6CtUndkFQFFBBEVF/Yl7EsgIYQsc+/5/TEsRmRPMnNn3s/HIw8YYJKTnJl73nzOuecYa61FRERERCqNE+0GiIiIiMQbBSwRERGRSlblActaS2FhIZqJFBERkURR5QFr165dZGZmsmvXrqr+UjGvoKAg2k2Q46B+Cyb1WzCp34JLfVeRpgirked50W6CHAf1WzCp34JJ/RZc6ruKFLBEREREKpkCloiIiEglU8ASERERqWQKWCIiIiKVTAFLREREpJIpYImIiIhUMgUsERERkUqmgCUiIiJSyWI+YF0yPcz/zAxT7uuoHREREQmGmA9Yl7Z0mLDC8qNpHqWeQpaIiIhUrrfW+Hy9o3IzRswHrPObO7w+yGXyOst5kz2KwwpZIiIiUjn+sMjjvCkeH29JsIAFMLypwztDXD7cbBk2yWNXmUKWiIiIHD9rLXcv8Pj1fJ97ujpc1dpU6ucPRMACOLOJw5ThLou2W85+12NHqUKWiIiIHDtrLXd87PPAZz5/PM3hd91cjEnQgAXQu4HDjBEhlhdaznwnzNY9ClkiIiJy9Hxr+dkcn8cX+/ylt8Odndwq+TqBClgA3eobPjgnxMZi6P92mA27FbJERETkyMK+5cqZHn9b4vNcP5ebTq2acAUBDFgA7bMMs84Jsasc+r0dZs0uhSwRERE5tDLPcskMjwkrLOMHulzVpmojUCADFkDr2obZ54bwLfR9K8yyAoUsEREROdiesOWCqR5vrbG8NshldMuqjz+BDVgAzdMjISstCfq9FearfIUsEREROaCo3HLOZI/3N1jeGuJyXrPqiT6BDlgATdIia7Kya0bWZH22TSFLREREoKDMMmSSxydbLe8NcxmcU32xJ/ABCyC7puH9ESFaZBgGvhNm7mY/2k0SERGRKNpWEtlx4OsdlunDXfo1qt7IExcBCyArxTBtuEuHOoZB73rM3KCQJSIikog2FVsGvB0mrwhmnhPitOzqjztxE7AAMmoY3hvm0quBYdh7Hu/lKWSJiIgkkrwiS7+3wuwohVnnhuhUt3I3ED1acRWwANKSDG8NdhnUxHDeFI/XVytkiYiIJIIVhZa+b4Up92H2uSHa1o5OuII4DFgAKSHDa4NcRjYzXDTNY8JyhSwREZF49s2OSOUq2Y1UrlpkRC9cQZwGLIAkxzD+TJcftzL8+H2Pv3+rkCUiIhKPPt9u6f92mKxk+OCcELm1ohuuAELRbkBVCjmG5/u7pIZ8rp3tURy23NK+6rbFFxERkeo1b4vP0EkeLTMMk4e51E2JfriCOA9YAI4xPNXHIS0Et871KQ7D2M4KWSIiIkE3a6PPiMkeHbMM7w51yawRG+EKEiBgARhjePh0h7Qk+NV8n91huLebgzGx0xEiIiJy9Kas8xk5xaNXA8Obg13SkmJrTE+IgAWRkHVvN5dU90DIeuR0hSwREZGgeWO1z8XTPQY1MfznbJeaodgbyxMmYO0ztrNL6nemC5/s4+AoZImIiATCyyt8Ln/f44LmhpcGutRwY3MMT7iABXBL+0gp8dpZkYXvf+/nEnJis4NEREQk4vklPtfM8ri8leG5/rE9didkwAK4uo1DTRd+MtNjT9jjxRhOwSIiIonuya88bv7I54a2Dk+dEfuzT3G7D9bRuLSVw3/Ocnl9jeXCaR4lYRvtJomIiMj3/PHzSLj6RXuHvwYgXEGCByyAC05yeHOwy7T1lnOneOwuV8gSERGJBdZa7vnUY+wnPnd3cXi0Z3BuTkv4gAUwNNdh0lCXuZstQyd5FJYpZImIiESTtZY75/nct9DnoR4O93V3AxOuQAFrvwGNHaYNd/lyh+WsdzzySxSyREREosG3lps+9Hn0S5//6+XwqwBuEK6A9R09GzjMGBFi1S7LwHfCbNmjkCUiIlKdwr7l6g88nv7G59m+bmCPuFPA+p6u9QwfnBNiyx7o91aY9bsVskRERKpDmWe5bIbHi8stLw10uaZtcGNKcFtehU7NMsw6N0RxGPq+FWZVoUKWiIhIVSoJR+7of2ON5dWzXS5tFeyIEuzWV6GTMw2zzw3hGOj3dpilOxWyREREqsLu8sid/NPWW94c7DKyefDjSfC/gyrULN0w65wQ6UmRkLU4XyFLRESkMhWWRe7g/3iL5b1hLkNy4yOaxMd3UYUap0XWZDWsCf3fDvPpVoUsERGRypBfErlzf/EOy9RhLv0bxU8siZ/vpArVr2l4/5wQJ2caznwnzIeb/Gg3SUREJNA2F1sGvBNmdZFlxogQPRvEVySJr++mCtVJNkwd5tK5rmHwJI8Z6xWyREREjse6Ikv/t8NsK4EPzgnRpV5wNhA9WgpYxyC9hmHSMJczGhiGT/Z4d61CloiIyLFYVWjp93aYPR7MOidEuzrxF65AAeuYpYYMbw5xGZJjGDnV47VVClkiIiJHY8lOS9+3w7gGZp8bolVmfIYrUMA6Lsmu4dWzXUY1N4ye7vHiMoUsERGRw/lie6RylZkEs84N0bRW/IYrgFC0GxBUSY7hpYEuqSGPK2Z6FIfh+lOUV0VERL5v/lafIZM8mteCKcND1EuJ73AF36tglZSUMHLkSFq3bk2nTp0YNGgQy5cvP+hJq1evxnVdOnfuvP9jxYoV1dboWOE6hmf7udzYzuGGOR5PLPai3SQREZGYMmeTz1nveLTNNMwYkRjhCn6ggnX99dczbNgwjDH85S9/4dprr2XmzJkHPTE9PZ1FixZVRxtjmmMMf+7tkBqCn8/12V0Ov+kSzIMpRUREKtO09T7nTfbomR1Zv1wrKTHCFXyvgpWSksLw4cMxJvID6NmzJ6tXr45GuwLFGMP/nubwu64Ody3wuWu+h7XakFRERBLXW2t8zpnsMaCx4Z2hiRWu4AhrsJ544gnOP//8H/y73bt3061bN6y1jBw5krvuugvXPXTlprCwsMLj5ORkkpOTj6PJsckYwz3dXNKS4M55PrvD8HhPZ39YFRERSRT/XuHz4/c9zmtmGH+mS7KbeGPhIQPWgw8+yPLly5k+ffpBf9eoUSPWr19PdnY2+fn5jB49mkcffZQxY8Yc8gvl5uZWeDxmzBjGjh17Ak2PTVfngC1NYsyiFHbuLuGRLqU4e19XO3bsiG7j5Lio34JJ/RZM6rfg2td3E9aEuHVBCqNywzzZpYTdBbA7ym2rDllZWRUe/2DAeuSRR5g4cSLTpk0jNTX1oL9PTk4mOzt7/ye8+uqrGT9+/GEDVl5eHhkZGRU+RzxVsL7rziyol+Fz7ewaeG4yz/d3Ce1NWd/vAAkG9Vswqd+CSf0WXBO31ObmBR7XtTX8tU9NXOfgDJEoDgpYjz32GBMmTGDatGnUrl37B5+0ZcsW6tSpQ1JSEqWlpUycOJEuXboc9gtlZGRUCFjx7qo2kYXvl7/vscfzGD9QC99FRCR+TVgT4pYFHje2c/hLby2RqbDIfd26ddxxxx3s3LmTgQMH0rlzZ04//XQAxo0bx9NPPw3AnDlz6NKlC506daJr1640bNiQu+66q/pbH+NGt3R4bZDLW2ssF0z12KNdHEREJA6NX+5zy4IUrm0bubM+0cMVgLFVfLtbYWEhmZmZFBQUJFQF67umrPMZOcWjT70wb49IScjFfkGWn5+vKYsAUr8Fk/oteP6z0ufSGR4XNy3nxUE1cRSuAB2VUy0G5zi8Mdhl9laX0dM9yn1t4SAiIsH3+mqfy2Z4jG5heKJbicLVdyhgVZNBOQ4v9NzDu3mWH8/wCCtkiYhIgL2z1ufi6R4XNDf8Y4CLJmcqUsCqRoMbebxypsvE1ZarPvDwFLJERCSAJuf5jJrqMSLX8NKZB+6UlwMUsKrZBSc5vDTQZfwKyw1zPHzt+C4iIgEyY73PyKkeg5oYXjnLJUnh6gcddid3qRqjWzqUenDlBx7Jrq/bWUVEJBBmbfQ5d4pH/0aGV892qaF5wUNSwIqSK1o7lPpw/WyPZAce1bE6IiISwz7a7DP8vcjBzf8d5JIS0ph1OApYUXRdW4dSz3LLRz4pIfh9d4UsERGJPZ9s8Rk2yaNbPcObg11qKlwdkQJWlN18qkupB7+c55Piwriu2vFdRERix8JtliGTPNpnGd4e4pKWpHB1NBSwYsAdHV1KPPjtAp9kB8Z2VsgSEZHo+2K7ZdC7YVpnGt4d6pJeQ+HqaClgxYi7ukQqWb+aH5kuvK29QpaIiETPV/mWs94N0zwd3hvmkqlwdUwUsGLIvd0cSjz4+dxIJeun7RSyRESk+i3ZGQlXjVNhyrAQdZIVro6VAlYMMcbwv6dFQtbPPvRJdg1XtdFWZSIiUn2WF1jOfCdM3WSYNjxE3RSFq+OhgBVjjDE80SuyT9Y1szySXbislUKWiIhUvVWFkXCVngTTR4SoX1Ph6ngpYMUgYwx/PcOhzLdcMdOjhgMXtVDIEhGRqrO2KBKukl2YMSJEw1SFqxOhgBWjHGN4tq9Liedx6YxIJevcZgpZIiJS+dbvjoQrYyLhqnGawtWJ0ogdw1zH8M8BLuc1M1w0zWNynh/tJomISJzZVBwJV2VeJFzl1lK4qgwKWDEuyTFMONNlcI5h5FSPGesVskREpHJs2RMJV0Xl8P45IZqnK1xVFgWsAKjhGv5zlku/hoZzp3jM2aSQJSIiJ2ZbieXsd8PsKI1UrlpmKFxVJgWsgEgJGf472OW0+obh73nM26KQJSIixye/JLJD+6biyN2CbWorXFU2BawASQ0Z3hri0iHLMGSSx8JtNtpNEhGRgCkoi5wtmFcUCVft6ihcVQUFrICplRQ5D6p1pmHQu2G+zFfIEhGRo7OrzDJ0ksfyQsvU4SE6ZClcVRUFrADKrGGYPMylaS04650w3+xQyBIRkcPbXW4Z/p7H1zssU4a7dKmncFWVFLACqk6yYerwENk14ax3wywvUMgSEZEfVhy2nDvZY1G+5b1hLj3qa/ivavoJB1i9FMP04SEykuDMd8Ks3qWQJSIiFZWELSOneMzbanl3iEuvBhr6q4N+ygHXINUwfUSIGm4kZK0rUsgSEZGIUs9y4TSP2Zssbw9x6dtIw3510U86DjRJM8wYEcK3kZC1sVghS0Qk0YV9y6UzPKZvsLwx2GVgYw351Uk/7TjRtFakklXsRRa+b9mjkCUikqistfx0jsebayyvnuUyOEfDfXXTTzyOtMyIrMnKL4VB74bJL1HIEhFJRHct8Pn7Estz/VzOaaahPhr0U48zbWpHQtaGYhg8yaOgTCFLRCSRPLHY46FFPo+c7nBFaw3z0aKffBw6NcswbXiIlbsiG8rtUsgSEUkILy33+flcnzs7OtzR0Y12cxKaAlac6lTXMGWYy1c7IneQlHkKWSIi8ey9PJ8rZ3pc2drwv6dpeI829UAc617f4Y3BLh9stFz5gYdvFbJEROLRvC0+F07zGJpr+FtfF2O0S3u0KWDFuYGNHV4a6PLyCssv5vpYhSwRkbjyzY7IEThd6hpeOcsl5ChcxYJQtBsgVe+iFg5Pllhu/NCnUSr8qrPm5UVE4kFekWXIpDCNU+GtIS6pIYWrWKGAlSB+1s5l8x749Xyf7JqGq9uoeCkiEmTbSyLhyjHw3rAQdZIVrmKJAlYCuaerw6ZiuG62R70UOE97o4iIBNLucss5kz22lsCcc0M0SVO4ijUaYROIMYYn+ziMbGYYPd1jziY/2k0SEZFjVO5bfjTd48t8y7tDXdrUVriKRQpYCcZ1DC8NdOmZbTh3ssfifC16FxEJCt9arv7AY9p6y38HufSor2E8VqlnElBKyPD6YJdmtWDIpDBrdilkiYjEOmstd87zeWm55V8DXAbpfMGYpt5JUJk1DJOGhUh2IyFrm84tFBGJaQ9/4fPYlz7/19thdEsN37FOPZTAGqUapgyLHA494j2PonKFLBGRWPT8Ep+xn/jc3cXh5lO11U4QKGAluFaZhklDQ3y903LRNI9yXyFLRCSWvLnG57rZHte3dbi3m4btoFBPCd3qG/47yGXGhsjiSR2pIyISG2Zv9Bk93eP8Zoan+jg6AidAFLAEgLObOLw4wOWl5ZFFlDpSR0Qkur7Mt5w7xaNnduTub1dH4ASKNhqV/S5u6bClxHLLRz4Na8KdnTTPLyISDat3RXZpb5EObwx2SdEROIGjgCUV3Hxq5EidMZ9EjtT5n9YqcoqIVKcteyyD3w2TGoJJQ0Nk1FC4CiIFLDnIfd0cNu+xXDMrcqTOiKYKWSIi1WFXmWX4ex6F5fDReSEapCpcBZVGTjmIMYan+ric29Two2keH23WkToiIlWt1LNcMNVjWYHlvWEhWmQoXAWZApb8oJBjGH+mS/f6hnMme3y9Q4veRUSqiudbrpjpMWez5c0hLp3rKlwFnQKWHFLNkOHNwS45aZHd3vOKFLJERCqbtZbb5vq8usoyYaBL/0YamuOBelEOq3ay4b2hIVwTCVnbdaSOiEiluv8znye/9nnmDJcLTtKwHC/Uk3JEjdMiR+psLYFzJnvs1pE6IiKV4umvPe751OeB7g7XttWQHE/Um3JUWtc2vDvU5ct8y8XTdaSOiMiJenWlz40f+tx6qsNvOms4jjfqUTlqPeo7TBzkMnW95dpZnnZ7FxE5TjPW+/z4fY9LWhoe76UjcOJRhYBVUlLCyJEjad26NZ06dWLQoEEsX778B5/49ttv07ZtW04++WRGjRpFYWFhtTRYomtwjsM/+rv8c5ll7CfavkFE5Fgt3GYZOdVjQCPDC/1dHIWruHRQBev6669nyZIlfP7555x//vlce+21Bz2pqKiIa665htdff51ly5bRuHFj7r///mppsETfpa0c/tTL4eEvfB79wot2c0REAmN5gWXYe2FOqW14bZBLDVfhKl5VCFgpKSkMHz58f6myZ8+erF69+qAnTZo0iS5dutC2bVsAbrzxRiZMmFD1rZWYcVt7l193dvjlPJ9/LVMlS0TkSDYWWwZPClOnBrwz1KVWksJVPDvsUTlPPPEE559//kF/vnbtWpo1a7b/cfPmzdm4cSPhcJhQ6Ic/5fenEJOTk0lOTj6eNkuM+H13h83Flqs/8KifAkNztaRPROSH7Cy1DJ0UpsyH90eEqJeicBXvDhmwHnzwQZYvX8706dMr5Qvl5uZWeDxmzBjGjh1bKZ87KHbs2BHtJlS6h06FdYU1+dE0y+SBxbTNiL9qVjz2WyJQvwVTPPZbqQcXzanJ2l0u7wwoJr3cJz8/2q2qfPHYd8ciKyurwuMfDFiPPPIIEydOZNq0aaSmph70902bNmXq1Kn7H69evZpGjRodsnoFkJeXR0ZGxv7HiVrB+n4HxINXh1j6vBXm8o/TmHd+iPo14+9/ZvHYb4lA/RZM8dRv1louf9/j0x2W6cNdejesHe0mVal46rsTddCczmOPPcaECROYOnUqtWv/8Ath6NChLFy4kG+//RaAp556iksuueSwXygjI6PCRyKGq3iVXsPw1uAQu8MwaqpHqaftG0REAH630Gf8Css/+7v0aahlFImkQm+vW7eOO+64g507dzJw4EA6d+7M6aefDsC4ceN4+umnAUhPT+fZZ59l5MiRtGrVinXr1nH33XdXf+slZjRLN/x3kMsnWy0/m6M9skRE/rXM576FPg/2cLi4pcJVojG2ikfCwsJCMjMzKSgoqDBFmIjy8/Pjvnz64jKfn8z0ePh0h192dKPdnEqRCP0Wj9RvwRQv/TZro8/Z73r8pJXh2X5uQmwkGi99V1kOexehyLG6/GSHb3ZaxszzaZ1pOK+Z/tcmIoll6c7IRqJ9Gxqe7psY4UoOptFPKt393R1GNjdcNsPji+2aKhSRxLGtxDJicpiGNeG1s12SHIWrRKWAJZXOMYZ/DXA5ORPOnRJmc7FClojEv1LPcsEUj4IyeGdIiNrJCleJTAFLqkRakuHNwSHKPLhgqkdJWCFLROKXtZFNlxdss7w52OWkDIWrRKeAJVUmt5bhjcEun223XDdbdxaKSPzavx3DAJeeDTS0igKWVLHTsh1e6O/y4nLLQ4vib5d3EZF92zE81MPhRy00rEqE7iKUKje6ZeTOwrsW+LStbRh1ki5AIhIfZm30uWaWxzVtDGM76domByhgSbUY1zUSsn4y06N5uqFrPa1PEJFg27cdQ7+Ghr+eoe0YpCLFbakWjjE839+lXW3DeVPCbNSdhSISYN/djuFVbccgP0ABS6pNaiiy6B3g/Ckee3RnoYgEkLZjkKOhgCXVqnFaZPuGxfmWqz7QnYUiEizWWm6Y7TFf2zHIEShgSbXrWs/wr4Eur6y03LdQdxaKSHA8/qXPP5ZZnuun7Rjk8PTqkKi48CSHB7o7/G6hzysrFLJEJPZNyvO58xOfX3VyuKyVhk85PN1FKFHzm84OX++wXPmBR4sM6FFfFywRiU3f7rRcMt1jeK7hge66VsmR6VUiUWOM4e/9XDrXNZw/xWNdkdZjiUjs2VFqOX9KmCZp8NJAF1d3DMpRUMCSqEoJGV4f5BIycN6UMLvLFbJEJHaEfculMzy2lsCbg0Nk1FC4kqOjgCVR1yDV8NaQEEsL4IqZHr7uLBSRGDH2E59p6y3/OculVabClRw9BSyJCZ3qGsaf6fLf1ZZxC7ToXUSi74WlPo996fN4T4ezmmi4lGOjV4zEjPOaOfzhNIffL/J5ablClohEz9zNPjfM9ri2jeHmUzVUyrHTXYQSU+7sGLmz8JpZHi3SoZf2mRGRarauyHLBVI/T6hue7KMzBuX4aPSSmGKM4Zm+Lj3qGUZO9VizS+uxRKT6FIcjBzgnu/DaIJcarsKVHB8FLIk5ya5h4iCXVBfOnRJmV5lClohUPWsj1fNvdlreGBwiu6bClRw/BSyJSfVrRu4sXL0LLp/p4fkKWSJStR5a5PPyCss/B0T25xM5EQpYErPaZxlePtPl7bWW38zXoncRqTpvrPa5a4HPPV0dLjxJQ6OcOL2KJKYNb+rwyOkOf/zC54WlClkiUvkW51sun+kxqrlhXFcNi1I5dBehxLyft3f4Zqfl+tkeLdOhbyNdAEWkcuwstYycGqZFOvxjgIujOwalkmikkphnjOEvvV36NDBcMNVjZaHWY4nIifOt5YqZHttL4L+DQtRKUriSyqOAJYFQwzW8erZL7WQ4d3KYIp1ZKCIn6H8/93lrreVfA1xaZChcSeVSwJLAqJtieGtwiDVFcOMcD6szC0XkOE1f7/PbBT53dXY4p5mGQql8elVJoJxSx/D0GS7/Wm55YakClogcu3VFlktneJzZ2HBvNw2DUjX0ypLAufxkh6tbG2760OOrfIUsETl6ZZ7lR9M9UlwYP9DFdTQ1KFVDAUsC6c99XFpkwMXTw+zWeiwROUq/nOfz6TbLf852qa+d2qUKKWBJIKWGDP8+K8TqIrjlIy/azRGRAJiw3OfPX/n8qZfD6dka/qRq6RUmgdWuTuSk++eXWv61TJuQisihfZVvuXa2x+WtDD87RUOfVD29yiTQrmztcMXJhp/N8fh2p6YKReRghWWWUdMim4k+fYaL0WaiUg0UsCTwnuzjklsrsh5rT1ghS0QOsNZy9SyPTcXw2tkh0rSZqFQTBSwJvFpJkfVYywrgtrlajyUiBzz+pc9rqywv9HdpXVvhSqqPApbEhQ5Zhj/3dvnbt5YJy7UeS0Rg1kafMZ/43NnR4YKTNNxJ9dIrTuLGNW0Ml7U0XD/HY6nWY4kktI3FltHTPc5oaHiwh4Y6qX561UncMCayy3vj1Mh6rBKtxxJJSOV+JFwZAy+f6RLSZqISBQpYElfSa0TWY31bALd/rKlCkUT060985m62/Pssl4apClcSHQpYEnc61TX8qafDX7/x+fcKhSyRRPLqSp9Hv/R5+HSHMxpqiJPo0atP4tINpzhc3MJw7WyPFYWaKhRJBEt2RrZkuLiF4bb2Gt4kuvQKlLhkjOFvfV2ya0bWY5V6Clki8ayo3DJqapgmafBsX20mKtGngCVxK2PveqzF+XDnPE0VisSzmz/0WFMU2Uw0vYbClUSfApbEta71DI/2dPjzVz4TVylkicSjl1f4/GOZ5ck+Lu3qKFxJbFDAkrh3UzuHUc0NV8/yWKX1WCJxZc0uy0/neFzS0nDFyQpXEjsUsCTuGWP4ez+XrGQYPcOjTOuxROJC2Lf8+H2P2jXgr3207kpiiwKWJITayYZXznJZtN3yq080VSgSDx5c5DN3i+XFgS61kxWuJLYoYEnC6FHf4Y+nOTy+2OfNNQpZIkH20Waf+xb6/LaL9ruS2KRXpSSU29o7nN/McOUHHmt2aapQJIgKyiw/nuFxWn3D3V00jEls0itTEooxhuf6uaQnwSUzPMp9hSyRoLnpQ4/8UnhpoM4ZlNilgCUJJyvF8MqZLgu2Wu6ar6lCkSB5cZnPS8stfz3D5aQMhSuJXQpYkpB6NnB46DSHh7/weWetQpZIEKwstNz4ocflrQyXtdLwJbGtwiv01ltvpXnz5hhjWLRo0Q8+YfXq1biuS+fOnfd/rFixoloaK1KZbu/gMCLX8D8zPdYVaapQJJaV792SoV4KPNnHjXZzRI6oQsC66KKLmDNnDs2aNTvsk9LT01m0aNH+j5YtW1ZpI0WqgmMM/xjgUjMEl87wCGs9lkjMun+hz/ytlvEDXTJ0FI4EQIWA1a9fP3JycqLVFpFqVzfF8PKZLnO3WMZ9qqlCkVg0e6PP7xf5/K6rQ88GmhqUYDiuV+ru3bvp1q0bXbt25b777sPzvCM+p7CwsMJHaWnp8XxpkUrXp6HDA90dHlrkMzlPIUskluwojUwN9mlg+HVnhSsJjtCxPqFRo0asX7+e7Oxs8vPzGT16NI8++ihjxow57PNyc3MrPB4zZgxjx4491i8faDsnAPYnAAAgAElEQVR27Ih2E+QQrs2FaWtrcvn7PjPPKqZRzQPTheq3YFK/BdN3+81auPaTFArKQvylSxEFOzWNH8sS/T2XlZVV4fExB6zk5GSys7P3f7Krr76a8ePHHzFg5eXlkZGRUeHzJCcnH+uXD7zvd4DEjgmDLJ0nhrnps3SmDa+4v476LZjUb8G0r99eWOrz+jqPV8506ZhTJ8qtkqOh99wBx1xv3bJlC+Xl5QCUlpYyceJEunTpcsTnZWRkVPhIxHAlsa1+TcOEM11mb7Lct1BThSLRtKzAcvOHHle1NlzcUlODEjwVXrU33HADOTk5rFu3jiFDhtCqVSsAxo0bx9NPPw3AnDlz6NKlC506daJr1640bNiQu+66q/pbLlIF+jVyuLerwwOf+by/QSFLJBrKPMtlMzwap8L/9daWDBJMxlpbpZPahYWFZGZmUlBQUGGKMBHl5+erfBoAnm85693IWYVfXhSibNcO9VsA6f0WTPn5+Ty8PJNHvvD56HyXHvVVvQoKvecq0itX5Htcx/D3fi6b98CvP1EVS6Q6zd7i8r+f+zzQ3VG4kkDTq1fkB7TMMDzYw+EvX/t8tFVTFCLVYUep5WcLUhjQyHBnJw1PEmx6BYscwi2nOvRuYLj10xSKw7o9XKSq3fGxx+6w4Z8DXByj3dol2BSwRA7BdQzP9XPZuMdw9wJNFYpUpanrfJ5farmvQyk5tRSuJPgUsEQOo01tw6/alfL4lz5zNytkiVSF3eWW62d7DGxkuLx5ebSbI1IpFLBEjuDG1uX0qG+4epZHiaYKRSrdbxf4bN4Df+vnoplBiRcKWCJH4Bp4vr/LykL4nTYgFalUH2/2eWKxz/3dHVpmKF1J/FDAEjkK7eoY7unq8PAXPvO3KmSJVIYyz3LtbI9u9Qy3tddwJPFFr2iRo3RnJ4fOdeGqDzxKPU0Vipyohxb5LNkJf+9X8exPkXiggCVylJIcw/P9QiwtgAc+UxVL5ER8lW/5/SKfX3V26FhX4UrijwKWyDHoWNdwV2eHhxb5fLZNVSyR4+H5lmtme7TMgN920TAk8UmvbJFj9OvODqfWgas+CFOmqUKRY/bnr3w+2WJ5tq9LsqvqlcQnBSyRY1TDNTzfP8TiHfCHzzVVKHIsVhVa7lrgc1M7hz4NNQRJ/NKrW+Q4dK1nGNvJ4YHPfL7MVxVL5GhYa7l+jke9FHiwh4YfiW96hYscp3FdHU7OiNxVGPYVskSO5B/LLNPWW545wyW9hqYGJb4pYIkcp2TX8Hx/l8+2Wx75QlOFIoezqdjyi7keP2llGJqroUfin17lIifgtGyHOzo43POpzzc7VMUSOZRbPvJIcuDxXm60myJSLRSwRE7Qvd0cmqfD1bM8PE0Vihzkv6t8Xl1l+XNvl7opmhqUxKCAJXKCaoYiU4Xztlj+tFhThSLftaPUcuOHHuc2NVzcQuFKEocClkgl6N3A4bb2Dr9d4LO2SFUskX3unOdRHIan+rgYo4AliUMBS6SS3NfNoXYNGDPPi3ZTRGLC9PU+f19i+ePpDjm1FK4ksShgiVSS9BqGP5zm8spKy+yNmiqUxFYctlw/26N/I8N1bTXUSOLRq16kEv3kZEOP+obb5mrBuyS2cQt8NhTD3/q6OJoalASkgCVSiRxjeKKXw2fb4fmlCliSmD7danl8sc+93RxOzlS4ksSkgCVSyXo1cLi8leE38z0KyhSyJLFYa/nFxx7tasPtHTTESOLSq1+kCvzhNJfdYbh/odZiSWJ5Y41l9ibLI6e7hBxVryRxKWCJVIEmaYbfdHZ4YrHPkp2qYkliKPMsY+Z5DG5iGKLjcCTB6R0gUkVu7+CQkwZ3fKxtGyQxPPONz4pd8EhPHYcjooAlUkVqhgyP9HR5J88yKU9ThRLfdpZa7l3oc1VrQ4csTQ2KKGCJVKFRzQ0DGhl+MdejXNs2SBx7cJHPHg/u767qlQgoYIlUKWMMf+rlsqwQnvxKVSyJT6t3WZ5Y7DOmo0OjVFWvREABS6TKdapruL6tw+8W+mzdoyqWxJ9fz/eomwK/7KghRWQfvRtEqsF93RwMcPcCVbEkvszb4vPyCssD3V3SklS9EtlHAUukGtSvafhdN4f/963Pou2qYkl8sNZyx8c+HbPgf05WuBL5LgUskWpyYzuHNrXh53M9rFXIkuD772rLh5sjm4q62lRUpAIFLJFqkuQY/tTT5YONltdWKWBJsJV5lrGfeAzNMQzK0VAi8n16V4hUoyG5Duc0NfxynseesEKWBNdfv/FZuQsePl3bMoj8EAUskWr26OkuG4rh0S+04F2CaUep5b6FPte0MbTXpqIiP0gBS6Sata5tuK29w0Of+6wrUhVLguf3n/mUenBvN1WvRA5FAUskCn7bxaFWEvxqvs4plGBZWWj581c+YzppU1GRw1HAEomCzBqGB7u7vLTc8tFmTRVKcPx6vke9FLijg4YPkcPRO0QkSq5sbehaD277yMfXtg0SAHM3+/x7pTYVFTkaClgiUeI6hid6uSzYZvnXMgUsiW37NhXtlAVXaFNRkSNSwBKJojMaOlx4kuHehR7lvkKWxK7XVlnmbrE80lObioocDQUskSi7p6vLql3woqpYEqP2bSo6LNdwdhMNGyJHQ+8UkSjrkGUY1dzw+0UeYVWxJAY9+bXP6iJ4+DRtyyBytBSwRGLA3V1dVhTCS8sVsCS25JdY7v/M59o2DqdqU1GRo6aAJRIDOtc1nN/M8MBnqmJJbHngM59yH+7tpuFC5FjoHSMSI8Z1dVleCBNWKGBJbFhRaPnL1z5jOzo01KaiIsdEAUskRnStZzi3aaSK5amKJTHgd5961E+B2ztqqBA5VnrXiMSQe7q6LC2Al1cqYEl0rSi0jF9hGdvJITWk6pXIsVLAEokh3eobRuQa7l+oKpZE1x8WRY7Eua6thgmR46F3jkiMuaebw5IC+M8qBSyJjrVFln8ss/yyg0NNVa9EjosClkiM6VHfYdjeKpbOKJRo+OPnPulJ8LN2GiJEjleFd8+tt95K8+bNMcawaNGiQz7p7bffpm3btpx88smMGjWKwsLCKm+oSCK5p6vD1zvhVa3Fkmq2sdjy7BKfX7R3qKUDnUWOW4WAddFFFzFnzhyaNWt2yCcUFRVxzTXX8Prrr7Ns2TIaN27M/fffX+UNFUkkp2c7DMkx3PeZqljHauLEiXTr0pncJk3o1qUzEydOjHaTAuXRL3xSXLilvapXIieiwjuoX79+5OTkHPYJkyZNokuXLrRt2xaAG2+8kQkTJlRdC0US1LiuDl/tgIlai3XUJk6cyIUXXkitHRu4o0czau3YwIUXXqiQdZS2lVj++o3PLac6ZNZQ9UrkRISO9Qlr166tUOFq3rw5GzduJBwOEwod+tN9fxoxOTmZ5OTkY/3yIgmjdwOHs5v43PeZx6iTDI7RgLePtZZvd8LSAsvqIsuaXbCmyDLll/fSt2k9Xjy/C8YYruvSjMteX8i1Y+7jtdrnkZVs6FHf0L+RoVm6fp7f99TXPtbCbapeiZywYw5Yxys3N7fC4zFjxjB27Njq+vIxYceOHdFughyHaPbbL1q5jPgglZcW72JEk3DU2hELSjz4cKvLextDTNkUYl1xJAQkO5acVEvTVJ/SDUsZcFozzN4waoxhYLO6fDxvCWsLy1lQYvjL15EDi3NSfXrX8+hdz6NXvTAta1kSOcOWePCXxWlc2iyMU7yL/OLotEPXyeBK9L7Lysqq8PiYA1bTpk2ZOnXq/serV6+mUaNGh61eAeTl5ZGRkbH/caJWsL7fARIM0eq34VnQ59swL6xN5Scdqu3/QzGjJGx5eaXljdU+U9dbdoeheS244CSHEbmGTnUN2TXZX93rdkobPli7geu6REKWtZaZa7fT6dS2zB5ZE4gcXjxns+WDjQ6zNrq8+pnFt3BSOtxyqsM1bRwyEnB67NlvfbaVevyqeypZmWlRbYuuk8GlvjvgmK/YQ4cO5aabbuLbb7+lbdu2PPXUU1xyySVHfF5GRkaFgCUiR+fGdg4/ft/jmx2WU+okxsBfHLY8843Pw1/4bCqGXg0Mv+3icE5Th1PrsL9C9X133T2OCy+8kB+/sZABTesyc+12Zq/ZxsTH/9/+f5OVYjivmeG8vSsdCsssH222vLTcZ8w8n9996nP9KQ63nuqQWysxft6+tTz2pcd5zQwnZybG9yxS1SpMtN9www3k5OSwbt06hgwZQqtWrQAYN24cTz/9NADp6ek8++yzjBw5klatWrFu3Truvvvu6m+5SIK48CRD/RR4+hs/2k2pckXlloc/9zjp5TB3zvMZmmNYenGID88L8avOLu2zzCHDFcCoUaN47bXXKM7K4dH5ayjOymHixIlccMEFh3xORg3D0FyHfw0MsfrSED9r5/Dstz4nvRzmshlhPt0a/zcZvJdn+WYn3NFBa69EKouxtmrvAS8sLCQzM5OCgoKEr2Dl5+erfBpAsdBvv5nv8eRXPht+HCItDvcmKglbHl/s8+gXPoXlcGVrw686ubTIOP7v9UT6rajc8twSnz8t9lm1Cy5obnj6DJfsmvH3swc4650wu8ph3vnuYQNsdYiF95scH/VdRfrvikgA3NDWYVc5jF8Rf9WUxfmWHq+HuedTn4tbOCy7OMT/6xs6oXB1omolGW5t77Ls4hAvDXSZvcnS/tUw/10Vf1XERdstMzZY7ujgRD1cicQTBSyRAGiWbjinqeHJrzyquOhcbay1/HmxR/fXw1jg0wtCPHWGG1PbJ7iO4bJWDosvDNG7gWHUNI8r3g+zszQ++gDg0S88mtWKTEWLSOVRwBIJiJvaOXyeD3O3BH9w37LHcs5kj1vn+lzXxmH+yBAdsmJ3gG+QavjvIJd/9Hd5Y42lw2thpq4LfjVrc7HllZWWW091CDmx+/MXCSIFLJGAGJRjaJkR2QwyyCbl+XR4Lcz8rZa3h7j8uY9LzVDsD+7GGK5o7fDlRSHaZBoGT/K4+UOPUi+4gff5pT6ugStbaygQqWx6V4kEhGMMPzvF4T8rLVv2BHNQf/hzj+HveXSta/jiwhAjmgbvEtS0lmHKcJc/93b4+xKfkVM89oSD1x+eH9kKY3QLQ1ZK7AdckaAJ3tVNJIFd2drBMfDckuBVsR77wmPMJz6/6ezwzlCXhqnBHdQdY7j5VJe3h7h8sNFy/hSP4oCFrCnrLauL4GftNAyIVAW9s0QCpG6K4ZKWhqe/8fH84Azo/7fY4455Pr/u7PBAdyduzlU8q4nDu0NdPtxsOXeyx+7y4PTJ09/4dK4Lp9WPj74QiTUKWCIBc2M7hzVFMCkvGIP5U1973DbX55cdHX7fPf62AhjQ2OG9oS6fbLWMmOxRFICQlVdkeXut5aenxF9/iMQKBSyRgOlR36F7PcNTAdjZ/f9943PThz4/b+/wx9PidzDv28hh8jCXhdsswyZ57CqL7ZD17BKf1BBc1lJDgEhV0btLJIBubOfwXp5lRWHsDuTPLfG5YY7Hze0cHusZv+Fqn94NHKYOd/ki3zJkkkdBjIasct/yt299Lm/lkJ6Ah1qLVBcFLJEAGt3SUDs5ds8n/OdSn2tnefz0FIf/6x3/4Wqf07Mdpo1w+WanZeik2NzC4a01lo3F8NNTdPkXqUp6h4kEUGrIcFVrh+eW+DG3RcDba3yumuVxTRvDk30SJ1zt06O+w5ThLp9us9w1P/YC8LNLfHpmGzrVTax+EaluClgiAfWzUxzyS+HfK2MnYG0rsVwz22N4ruGZvm7c3C14rHrUd3ioh8OjX/pMWx87IWtzsWXKOsv/nJyY/SJSnRSwRAKqVaZhSI6JqZ3db/rQI+zD3xI4XO3ziw4OZzU2XDHTY3tJbITgV1b6OAZ+1EKXfpGqpneZSIDd2M7hk62WhduiP4D/e4XPv1danuwT7E1EK4tjDP8Y4FLqwXWzY+OQ7heXW4bnGupq53aRKqeAJRJgw3MN2TVh/PLoVrE2F1tu/NDjopMMo1to8N6nSZrh2b4u/11t+fuS6AaspTst87daftxKl32R6qB3mkiAhRzDhc0d/r3Sj1qFxFrLDXM8HANP9XETblH7kVxwksO1bQy3zfVYujN6IeulFT4ZSXBOU/WPSHVQwBIJuNEtDXm74eMt0Rm8X1xueWON5ZkzXOrX1OD9Q/7UyyUnDS5736MsCls3WGt5cZnPRScZaobURyLVQQFLJODOaGBoWDM6dxOu32255SOPy1oaLjhJl5NDSUsyvDTQ5fPtlt8trP7p3I+3WFbugstPVh+JVBe920QCznUMP2rh8J9VPn41ThNaa7l2lkdqCP7c2622rxtU3es73N/d4Q+LfD7YWL0h66Xllpw06N9I1SuR6qKAJRIHLm5hWL8bPtpcfQHr70ss762z/K2vS5buSjsqd3Z06NvQcMNsj7BfPX1V7lteXuFzaUsn4bfOEKlOClgicaB3A0OTNHhlRfUM2muLLLd/7HFVa8OIprqMHC3XMfypl8uSAnhhafX01ZR1lu2lcLnuHhSpVnrHicQBxxh+dJLDq6t8vGqojNzzqUdaCB7vpanBY9WlnuGSlobfLfSq5ZijV1f5tK0NHXU0jki1UsASiROjWxg27YHZm6p20F5RaPnXMsvYTg6ZNTRoH4/7u7lsLoYnq3gX/rBveWuN5YLmutSLVDe960TixOnZhqa1qv5uwocWedRLgetP0eXjeLXKNFzb1uHBRT47S6uuv2ZvikwPXtBcQVikuukKKRInjDFc3CIyTVhVC6hX77L8Y6nlzo4OqdpP6YTc3cWhJAyPfFF1VayJqyJ3D3avp74SqW4KWCJx5OIWhq0l8GEV3U344CKPOsnwU1WvTljjNMNt7R0eX+yzrQoOg7bW8voanwuaO9pdXyQKdJUUiSPd6hnqp0TuHKtsa3ZZXlhq+WVHh7QkDdiV4fYODp6F55ZUfhXr022Wdbs1PSgSLQpYInHEMYazmximrq/8gPWHz30ya8CN7XTZqCz1axouaWF46uvKv/vz3TxLRhKc0VABSyQadKUUiTODmjgs2GrZXonTTjtLLS8s9bntVIdaql5VqptPdVhTBO/kVW7AmpRnGZxjSHLUXyLRoIAlEmcGNTFYYHolVrFeXuFT7sM1bXXJqGzd6zucnm34y1eVN024rcQyb4tlWK76SyRa9O4TiTM5tQztasPU9ZU3YD+31DIs19AoVdWQqnBzO4ep6y3f7qycUDxlncUCQ3PUXyLRooAlEocG5ThMWW+xlXD48+J8y/ytlqtb63JRVX7UInJzwlOVtPHopDyfTlmROxVFJDp0xRSJQ4ObGNYWwbKCE/9czy/1qZcCI5pqsK4qya7h+rYOLyz12VV2YqHYt5bJ6yzDdUakSFTpHSgSh/o3MiQ5MOUEpwnLPMu/lvn8pJVDDVcBqyrdcIpDcRjGrzixPvsiH7aWwBBND4pElQKWSBxKSzL0aWBOeD+sd9ZatpbA1W10qahqubUiW2xMWHFifTZzg0+KC6fXV8ASiSZdNUXi1OAcw/sbLeUnsL/Sc0t9etQ3tM/SYF0dLmnpMGujZf3u4++z9zdaemUbUnSUkUhUKWCJxKlBTQxF5fDxcR6bs7HY8m6e5arWGqiry8hmkand/6w8vmlCz7fM2mgZ0Fh9JhJtClgicapLXUPdZI57V/dXVviEDFzaUpeJ6lI72TAs1/DyyuPrsy/yYWcZDGikgCUSbbpyisQp1zGc1cQw5TgD1ltrLWc2NtRO1mBdnUa3cJi3xbJm17H328yNe9dfZavPRKJNAUskjg1u4jB/q2VH6bEN1gVlkammc5tpoK5uw5saXAPv5h37NOHMjZbeDQzJuuNTJOoUsETi2IDGBt/C3GNch/VeniVs4RztpVTtMmsYzmhoePcYzyb0bSQU99f0oEhM0NVTJI61SIfsmvDRMQast9ZGdgJvWkuDdTSMyDVMX28pCR99vy0riKy/6qXpQZGYoIAlEseMMfTKNszdcvQDddiP3D14bjNdHqJleK7DHi8y5Xe05m+N/Nvu2v9KJCboCioS53plGz7Zagkf5X5YC7ZadpTC8FwN1NHSrg40q8UxTRN+stVycgbU0U0JIjFBAUskzvVqENkP6+sdR/fvZ22ypIVUCYkmYwxDcxymrDv6he6fbLWcpulBkZihgCUS57rUNRjg021HVw35YO+daEmOButo6t/IsKQAtu45cr+VeZbPtllOUygWiRkKWCJxLr2GoW1tWHAUAcvzLXM26U60WHBGw0gfzNl05H77Mh/KfBSwRGKIApZIAuhWz7Bg65EH6kXbobAcBawYkFvL0KwWzDmKO0A/2RrZdb9zXfWbSKxQwBJJAN3rGz7PP/LBzx/s3Qm8hyohMeGMhobZR1HB+mSrpWNddMCzSAxRwBJJAF3rGko9+Hbn4f/drE2WXtnaCTxW9G1oWLjNsrv88CFrwVZLj3q6nIvEEr0jRRJA+6xIYPoy/9ADtbWWDzdb+mp6MGac0cDBszDvMPuYlXmWb3dCx7rV2DAROSIFLJEEUCfZkJN2+IC1pgi2lUCPegpYseKUOlAn+fA78S8pgLCFjlnqN5FYooAlkiA6ZBm+OEzA2reNQzetv4oZjjF0OkK/7QvN7euo30RiyUEBa9myZfTu3ZvWrVvTo0cPvvrqq4OetHr1alzXpXPnzvs/VqxYUS0NFpHj06GOOWwFa8FWS5M0aJSqgTqWdDyKgJWbBrW1g7tITDkoYN1www1cf/31LF26lLFjx3LllVf+4BPT09NZtGjR/o+WLVtWdVtF5AR0rGvI2w0FZT88WH+6zdJN04Mxp2OWYVkhFB/i4Ocv8+3+NXYiEjsqBKwtW7awYMECLr/8cgAuvPBC8vLyWL58eVQaJyKV55TakUF4acGhB+pOGqhjTocs8C18veOH+21Jgd3ftyISOyoErLy8PBo1akQoFAIi52E1bdqUtWvXHvTE3bt3061bN7p27cp9992H53mH/UKFhYUVPkpLSyvx2xCRIzk5I/Lr0oKD/25biWXTHq3jiUWn1okcdfRF/sF/V+ZZVu2CNpnqN5FYEzqeJzVq1Ij169eTnZ1Nfn4+o0eP5tFHH2XMmDGHfE5ubm6Fx2PGjGHs2LHH8+UDa8eOozxtV2JKPPVbg5Q0Pt9UyrCssgp/PnerC6SS4xaSn3/0BwzHsnjqtxa10pi/oYyR9Sv+x3TZLoNna9HQ2UV+/uH/kxsU8dRviSbR+y4rK6vC4woBKzc3l40bNxIOhwmFQlhrWbt2LU2bNq3wpOTkZLKzs/d/wquvvprx48cfNmDl5eWRkZFR4XMkJyef8DcUNN/vAAmGeOm3tnXCrC11ycqqVeHP1270SHJ8ejTNjKtDnuOl3zrXD7O02CUrK63Cn2/e5QMe3XMyyEpTv0n0qe8OqDBFmJ2dTdeuXXnxxRcBeO2118jJyaFVq1YVnrRlyxbKy8sBKC0tZeLEiXTp0uWwXygjI6PCRyKGK5Foa535w2uwFu+ANpnEVbiKJx2zDJ9vt1hbse+WFlhqJUGj1Cg1TEQO6aC7CJ955hmeeeYZWrduzR/+8Aeef/55AMaNG8fTTz8NwJw5c+jSpQudOnWia9euNGzYkLvuuqt6Wy4ix+zkDMPSAg4aqJcVWNpqoXTM6phl2F4Km/ZU/POlBZbWmZH1siISWw5ag9WmTRvmzp170D+877779v9+1KhRjBo1qmpbJiKVrnWmYXc4MlB/t+qxvNByaUvtOxyr9oXfJTtthX3KVhRCy3SFK5FYpCuqSAI5ae9gvHrXgQpWqWdZWwStMjRQx6qT0sExsLyw4p+v2mX396mIxBYFLJEE0iw98uvqXQf+bNUusECrzKg0SY5CsmtomhaZyt0n7FvyiqB5ehQbJiKHpIAlkkAyaxjqJMPqogMD9fK9g7YqWLGtZYZh5XcqjxuKI4c8N1cFSyQmKWCJJJjmtSpWsJYXWlJc3YkW65qnw5qiA4/X7g3JTeNoewaReKKAJZJgctIM63cfqISsLYJmtcDRnWgxrVktU2HtXN7esJVb6xBPEJGoUsASSTBN0gzriw8M1OuLLU1UBYl5zdMNW0tgd3mk79bttmQkQUYN9Z1ILFLAEkkwOWmwbveBx+t3QxNND8a83L2buK/f23d5uyN9KSKxSQFLJME0STNsK4GScKQSsn63pbEqWDFvX5VxX/VxY7H6TSSWKWCJJJhGNSO/bt4T2dF9Q7EqWEHQeG8fbSiO/Lqp+EBfikjsUcASSTAN9u4EvnmPZXsplPloDVYApCUZMmuw/waFTXssDVPVbyKx6qCjckQkvjXYW/XYsgeS3cjvm2gtTyA0Tv1OBWsPNFQFSyRmKWCJJJj6KWCITBE6JlINaaxKSCBk1zRs3WPZXW4pKj9QjRSR2KOAJZJgQo6hbkpkijAStaCh1mAFQv0U2FIC20oOPBaR2KSAJZKAsvcO1I6x1EmGJEeVkCDIrmlYVuCzvTTyuG6y+k0kVilgiSSgOsmGHaUW1xhVQQJkXwVre0lkareu+k4kZilgiSSgrGTYUQpgqZeiKkhQZNeErXsOTBHWTY5ue0Tk0LRNg0gCqpMM+aWRDw3SwVE32RC2sKbIkuRAraRot0hEDkUBSyQB7Zsi3FEaCVsSDPv6anmhpW4yGB3QLRKzFLBEElCdGrCjDPJLLVlaKB0Y+wLWykKorWAsEtO0BkskAdXZuwbLAJk1ot0aOVp1akTC8OoiS3ZNBWORWKYKlkgCqpNsKPEim40qYAVHxt6+yiuCTK2/EolpClgiCShj7+DsWcisoUpIUOzrt7BVMBaJdQpYIgko/TvVjwxVQgIj2YWkvVftDAUskZimgCWSgL57e3+6AlZgGGP2B+K0kCqPIrFMAUskAdVKOjA4pylgBcq+/tIeWCKxTQFLJAF9d3BOVSUkUNJCFW3elNsAAAtXSURBVH8VkdikgCWSgFJDP/x7iX37ArEqjyKxLaqX1qKiIjZs2IDv+9FsRqVwHIfGjRtTq1ataDdF5IhS3AO/VyUkWGru7TtVHkViW9QurR9//DG33347ZWVl0WpCpatRowaPPfYYPXv2jHZTRA7ruwFLFaxg2XcX4Xf7UERiT1QurUVFRdx+++10796d6667jqSk4Ne6y8vL+dvf/sbtt9/OlClTVMmSmBZyDlQ/aipgBcq+rkvWAg+RmBaVS+uGDRsoKyvjuuuuo0OHDtFoQpW47rrr+Oijj9iwYQOtW7eOdnNEjkoNDdSB4tvIrykKxiIxLSqX1n1rruKhcvVd+76feFhTJonD1VKeQNl3dVEFSyS26S0qkuCMUcIKElWwRIJBAesIVq9ezYABA8jMzKRz587Rbo6IJDi7N2CpgiUS2/QWPYKMjAweeOABxo8fH+2miIjsnyJM0TYNIjFNAWuvRx55hOuvv37/4507d1KvXj0AzjjjDNLS0qLVNBGR/cr3Jqya2qZBJKbFzCx+8f9v725jmtjSOID/662CrGJB0FWhkAZq1Q+2IIZgdhdN1MYoRcBEc/nQRCgJMcaXBGJQPuhCjOGaGF+Q1diEaPAm0stNjEh84V7dGHWRaCIuAsnWFtFldxErIaiV7ge0Wss7006n/H9JY8o4c57p42Eez5zOcbrQ2uu742sUoz+YLy8vD2q1GseOHYNCoYDZbIbBYEBkZKTvgiIimqAPn4buEXKRbqLAFjAFVmsvkPyL02fHf7RVjqSokbcrFArk5OTgwoUL2Lt3LyorK/Hzzz/7LB4iosl4/3kEi4s9EwW2gCmwNIqhIsiXxx/L7t27kZGRgWXLliE6Oho6nc5n8RARTcb7T0N/cokjosAWMF00TC4bdYTJHzQaDVQqFUwmE44dOyZuMEREw/jjbBn+9c6FH2ZwkjtRIOMk9+/k5+fD6XQiJycHANDf34+YmBhs27YNz549Q0xMDA4cOCBylEQ0XdVt+AH1es5wJwp0ATOCFSgaGxtRWFjofip7WFgYOjs7RY6KSHiZcTL8/d8uscOgCVowWwZ9LEeviAIdC6zPurq6sG7dOkRGRqKhoUHscIh87pcN7P5ERL7C37CfLV68GK2trWKHQUREREGAc7CIiIiIBMYCi4iIiEhgLLCIiIiIBMYCi4iIiEhgLLDGcPv2baxevRrLly/HihUrUFRUhMHBwbF3JCIiommLBdYYIiIicPnyZTx79gyPHj3CvXv3UF1dLXZYREREFMAkV2BZLBYk67T4Q9hsJOu0sFgsghy3oqICJpPJ/b63txdRUVGIi4uDSqUCAISGhkKr1cJqtQrSJhEREQUnSRVYFosF2dnZmPOmC/tXxWHOmy5kZ2cLUmTl5eWhrq4Ovb29AACz2QyDwYDIyEj333n9+jWuXLmCzZs3T7k9IiIiCl6SKrDKjhzGn+OicdGggykpHhcNOvwpLgrlfz0y5WMrFArk5OTgwoULcLlcqKysxK5du9zbHQ4HtmzZgqKiIqxatWrK7REREVHw8iqw2tvbkZaWBrVajZSUFLS0tAy749WrV6HRaJCYmIisrCw4HA6fB9v6/Dn+ooyETDa0DpdMJkO6cj7+KdAT2Hfv3o2zZ8/i+vXriI6Ohk6nAwC8e/cOer0eBoMB+/btE6QtIiIiCl5eBVZBQQFMJhPa2tpQXFwMo9HotVNfXx927tyJuro6tLe3Y/HixThyZOqjSGPRLF2K3209cLmGFqh1uVz4zfY/LNNohDm+RgOVSgWTyeQeverr64Ner4der8fBgwcFaYdIbL6ay0i+xbwRSYdHgdXd3Y2mpibk5uYCALKzs2G329HR0eGxU319PXQ6HTSfC5vCwkLU1NT4PNiSQ6W48+I/+PHXZvyt2Yoff23G3Rf/RcmhUsHayM/Ph9PpRE5ODgDgxIkTePjwISwWC7RaLbRaLcrKygRrj8jffDmXkXyHeSOSFo8Cy263Y9GiRZDLh9aAlslkUCqVsNlsHjvZbDbExcW538fHx+PVq1dwOp0jNuRwONyvvr4+9yjURGRlZaG2thb9kTH4qekF+iNjYLFYsHXr1gkfaySNjY0oLCzEzJkzAQAlJSX4+PEjHj9+7H6VlJQI1h6Rv/lyLiP5DvNGJC1yfzUUGxvr8V6lUsHpdI5alA0nIyMDGRkZHj+b6DGG09XVhQ0bNiAiIgLXrl2b1DGdTicGBwfR29uLnp4er+1v3ryZcpzkf8GWt9bW59ifEuc1l/Gnf7QO++9Wqpg3aQq2vE0n0z133z51APiuwIqNjXWPRMnlcrhcLthsNiiVSo+dlEolbty44X5vtVo9Rr6GY7fbER4eDgBoa2tDQUEB5HL5qPv4k1KpROsUJ8vL5XLMmDEDCoXC64P+YqSfU2ALprxpNEvxu60L+bqhi7V7LuMyTVCdJ8C8SVWwnc90wtx95XGLcMGCBUhKSsLFixcBALW1tYiJiUFCQoLHTnq9Hs3Nze6C5MyZM9i+ffuoDYWHh7tfc+bMcf8vjIj8yx9zGUl4zBuRtHh9i7CqqgpVVVVQq9U4evQozGYzAKC0tBRnz54FAMydOxfnz59HZmYmEhIS0NnZiUOHDo2/0RlDzX769EmIcwgYX87ny/kRBSJ/zGUk4TFvRNIic01mtvkEOBwOzJs3D2/fvnXfIuzu7samTZtQVlaGjRs3+rJ5v2poaEBJSQnq6+sRHR3ttb2np4fDpxLEvEkT8yZNzJt0MXeeRJkAFRUVhaSkJJw+fRoLFy5EaGioGGEIamBgAKdOnUJycjLmz58vdjhEREQkIlFGsADg5cuX2LFjB/r7+33ZvF+FhYWhpqYGS5Ys8dr2/v17lJaW4vDhwwgJCREhOpoM5k2amDdpYt6ki7nzJlqBBQAfPnyAzWYT5DELYpPL5VAqlZg1a9aw20f7HChwMW/SxLxJE/MmXcydN1GfkTBr1iyvbygSERERSR2/7kZEREQkMJ+PYH25A+lwOHzdVED7cv7T/XOQGuZNmpg3aWLepIu5GzJ37tyvqy34eg5WZ2en1zI5RERERMHm2zloPi+wBgcH0dXV5VHVEREREQUbv45gEREREU03nOROREREJDAWWEREREQCY4HlZ2azGTKZDHV1dWKHQmMYGBhAZmYm1Go1Vq5cifXr16Ojo0PssGgM7e3tSEtLg1qtRkpKClpaWsQOicaB/U36eH3zxALLj6xWK86dO4fU1FSxQ6FxMplMeP78OZ48eQKDwYC8vDyxQ6IxFBQUwGQyoa2tDcXFxTAajWKHROPE/iZdvL55Y4HlJ4ODg8jLy8PJkye5TpNEhIaGYtOmTe5vhKSmpsJqtYobFI2qu7sbTU1NyM3NBQBkZ2fDbrdzJEQC2N+ki9e34bHA8pPjx49jzZo1SE5OFjsUmqQTJ07AYDCIHQaNwm63Y9GiRZDLh56hLJPJoFQqYbPZRI6MJor9TTp4fRueqGsRThdPnz5FbW0t7ty5I3YoNEnl5eXo6OjArVu3xA6FKOixv0kHr28j4wiWj1RXV0Or1UKr1eLu3buwWq1ITExEfHw87t+/D5PJhMrKSrHDpO98mzez2QwAqKiogMViQX19PcLCwkSOkEYTGxuLV69ewel0Ahhaqstms0GpVIocGY0X+5u08Po2Mj5oVATp6enYs2cPMjMzxQ6FxnD8+HFcunQJN2/eREREhNjh0Dikp6fDaDTCaDTiypUrOHr0KJqamsQOi8aB/U36eH37ircIiUbQ2dmJ/fv3Q6VSYe3atQCAkJAQPHjwQOTIaDRVVVUwGo0oLy9HeHi4eySSAhv7GwUbjmARERERCYxzsIiIiIgExgKLiIiISGAssIiIiIgE9n8/jJCAxe83RAAAAABJRU5ErkJggg=="},"metadata":{"image/png":{"height":480,"width":600}},"execution_count":1}],"cell_type":"code","source":["f(x) = abs(cbrt(x^2-1))\na, b = -5, 5\ncps = find_zeros(D(f), a, b)\nplot(f, a, b)\nscatter!(cps, f.(cps))"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

In this example, the derivative has vertical asymptotes at $x=1$ and $x=-1$ so is not continuous there. The bisection method identifies the zero crossing, not a zero.

","metadata":{}}, -{"cell_type":"markdown","source":"

The search for all zeros in an interval is confounded by a few things:

","metadata":{}}, -{"cell_type":"markdown","source":"","metadata":{}}, -{"cell_type":"markdown","source":"

The algorithm is adaptive, so that it can succeed when there are many zeros, but it may be necessary to increase no_pts from the default of 12, at the cost of possibly taking longer for the search.

","metadata":{}}, -{"cell_type":"markdown","source":"

Here the algorithm identifies all the zeros, despite there being several:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":"Plot(...)","image/png":"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"},"metadata":{"image/png":{"height":480,"width":600}},"execution_count":1}],"cell_type":"code","source":["f(x) = cos(x)^2 + cos(x^2)\na, b = 0, 10\nrts = find_zeros(f, a, b)\nplot(f, a, b)\nscatter!(rts, f.(rts))"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

For nearby zeros, the algorithm does pretty well, though it isn't perfect.

","metadata":{}}, -{"cell_type":"markdown","source":"

Here we see for $f(x) = \\sin(1/x)$–with infinitely many zeros around $0$–it finds many:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":"Plot(...)","image/png":"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"},"metadata":{"image/png":{"height":480,"width":600}},"execution_count":1}],"cell_type":"code","source":["f(x) = iszero(x) ? NaN : sin(1/x) # avoid sin(Inf) error\nrts = find_zeros(f, -1, 1) # 88 zeros identified\nplot(f, -1, 1)\nscatter!(rts, f.(rts))"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

The function, $f(x) = (x-0.5)^3 \\cdot (x-0.499)^3$, looks too much like $g(x) = x^6$ to find_zeros for success, as the two zeros are very nearby:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["1-element Array{Float64,1}:\n 0.5"]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["f(x) = (x-0.5)^3 * (x-0.499)^3\nfind_zeros(f, 0, 1)"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

The issue here isn't just that the algorithm can't identify zeros within $0.001$ of each other, but that the high power makes many nearby values approximately zero.

","metadata":{}}, -{"cell_type":"markdown","source":"

The algorithm will have success when the powers are smaller

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["2-element Array{Float64,1}:\n 0.499\n 0.5 "]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["f(x) = (x-0.5)^2 * (x-0.499)^2\nfind_zeros(f, 0, 1)"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

It can have success for closer pairs of zeros:

","metadata":{}}, -{"outputs":[{"output_type":"execute_result","data":{"text/plain":["2-element Array{Float64,1}:\n 0.49999\n 0.5 "]},"metadata":{},"execution_count":1}],"cell_type":"code","source":["f(x) = (x-0.5) * (x - 0.49999)\nfind_zeros(f, 0, 1)"],"metadata":{},"execution_count":1}, -{"cell_type":"markdown","source":"

Combinations of large (even) multiplicity zeros or very nearby zeros, can lead to misidentification.

","metadata":{}} - ], - "metadata": { - "language_info": { - "file_extension": ".jl", - "mimetype": "application/julia", - "name": "julia", - "version": "0.6" - }, - "kernelspec": { - "display_name": "Julia 0.6.0", - "language": "julia", - "name": "julia-0.6" - } - - }, - "nbformat": 4, - "nbformat_minor": 2 - -} diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..a303fff2 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,2 @@ +build/ +site/ diff --git a/docs/Project.toml b/docs/Project.toml new file mode 100644 index 00000000..ab0bacee --- /dev/null +++ b/docs/Project.toml @@ -0,0 +1,4 @@ +[deps] +Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80" +ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210" diff --git a/docs/make.jl b/docs/make.jl new file mode 100644 index 00000000..80414650 --- /dev/null +++ b/docs/make.jl @@ -0,0 +1,15 @@ +using Documenter +using Roots + +makedocs( + sitename = "Roots", + format = Documenter.HTML(), + modules = [Roots] +) + +# Documenter can also automatically deploy documentation to gh-pages. +# See "Hosting Documentation" and deploydocs() in the Documenter manual +# for more information. +#=deploydocs( + repo = "" +)=# diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 00000000..f9bf02a7 --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1,83 @@ +# Roots.jl + +Documentation for [Roots.jl](https://github.com/JuliaMath/Roots.jl) + + +## About + +`Roots` is a `Julia` package for finding zeros of continuous +scalar functions of a single real variable. That is solving $f(x)=0$ for $x$. +The `find_zero`function provides the +primary interface. It supports various algorithms through the +specification of a method. These include: + +* Bisection-like algorithms. For functions where a bracketing interval + is known (one where $f(a)$ and $f(b)$ have alternate signs), the + `Bisection` method can be specified. For most floating point number + types, bisection occurs in a manner exploiting floating point + storage conventions. For others, an algorithm of Alefeld, Potra, and + Shi is used. These methods are guaranteed to converge. + + +* Several derivative-free methods are implemented. These are specified + through the methods `Order0`, `Order1` (the secant method), `Order2` + (the Steffensen method), `Order5`, `Order8`, and `Order16`. The + number indicates, roughly, the order of convergence. The `Order0` + method is the default, and the most robust, but may take many more + function calls to converge. The higher order methods promise higher + order (faster) convergence, though don't always yield results with + fewer function calls than `Order1` or `Order2`. The methods + `Roots.Order1B` and `Roots.Order2B` are superlinear and quadratically converging + methods independent of the multiplicity of the zero. + + +* There are historic methods that require a derivative or two: + `Roots.Newton` and `Roots.Halley`. `Roots.Schroder` provides a + quadratic method, like Newton's method, which is independent of the + multiplicity of the zero. + + + +## Basic usage + +Consider the polynomial function $f(x) = x^5 - x + 1/2$. As a polynomial, its roots, or zeros, could be identified with the `roots` function of the `Polynomials` package. However, even that function uses a numeric method to identify the values, as no solution with radicals is available. That is, even for polynomials, non-linear root finders are needed to solve $f(x)=0$. + +The `Roots` package provides a variety algorithms for this task. In this overview, only the default ones are illustrated. + +For the function $f(x) = x^5 - x + 1/2$ a simple plot will show a zero somewhere between $-1.2$ and $-1.0$ and two zeros near $0.6$. + +For the zero between two values at which the function changes sign, a +bracketing method is useful, as bracketing methods are guaranteed to +converge for continuous functions by the intermediate value +theorem. A bracketing algorithm will be used when the initial data is +passed as a tuple: + +```julia +julia> using Roots + +julia> f(x) = x^5 - x + 1/2 +f (generic function with 1 method) + +julia> find_zero(f, (-1.2, -1)) +-1.0983313019186334 +``` + +The default algorithm is guaranteed to have an answer nearly as accurate as is possible given the limitations of floating point computations. + +For the zeros "near" a point, a non-bracketing method is often used, as generally the algorithms are more efficient and can be used in cases where a zero does not. Passing just the initial point will dispatch to such a method: + +```julia +julia> find_zero(f, 0.6) +0.550606579334135 +``` + + +This finds the answer to the left of the starting point. To get the other nearby zero, a starting point closer to the answer cana be used. However, an initial graph might convince one that any of the upto 5 reaal roots will occur between `-5` and `5`. The `find_zeros` function uses heuristics and a few of the algorithms to identify all zeros between the specified range. Here we see there are 3: + +```julia +julia> find_zeros(f, -5, 5) +3-element Array{Float64,1}: + -1.0983313019186334 + 0.550606579334135 + 0.7690997031778959 +``` diff --git a/docs/src/reference.md b/docs/src/reference.md new file mode 100644 index 00000000..797669cd --- /dev/null +++ b/docs/src/reference.md @@ -0,0 +1,220 @@ +# Reference/API + +The `Roots` package provides several different algorithms to solve `f(x)=0`. + + +```@index +Pages = ["reference.md"] +``` + +```@setup reference +using Roots +``` + +```@meta +DocTestSetup = quote + using Roots +end +``` + +```@meta +CurrentModule = Roots +``` + +## The `find_zero` and `find_zeros` functions + +There are two main functions: `find_zero` to identify a zero of $f$ given some initial starting value or bracketing i nterval and `find_zeros` to heuristically identify all zeros in a specified interval. + + +```@docs +find_zero +find_zeros +``` + + +## Classical methods based on derivatives + +We begin by describing the classical methods even though they are not necessarily recommended because they require more work of the user, as they give insight into why there are a variety of methods available. + +The classical methods of [Newton](https://en.wikipedia.org/wiki/Newton%27s_method) and [Halley](https://en.wikipedia.org/wiki/Halley%27s_method) utilize information about the function and its derivative(s) in an interative manner to converge to a zero of `f` given an initial starting value. + +Newton's method is easily described: + +From an initial point, the next point in the iterative algorithm is found by identifying the intersection of the $x$ axis with the tangent line of `f` at the initial point. This is repeated until convergence or the realization that convergence won't happen for the initial point. Mathematically, + +$x_{n+1} = x_{n} - f(x_n)/f'(x_n).$ + +Some facts are helpful to understand the different methods available in `Roots`: + +* For Newton's method there is a formula for the error: Set $\epsilon_n = \alpha - x_n$, where $\alpha$ is the zero, then + +$\epsilon_{n+1} = -f''(\xi_n)/(2f'(\xi_n) \cdot \epsilon_n^2,$ + +here $\xi_n$ is some value between $\alpha$ and $x_n$. + +* The error term, when of the form $|\epsilon_{n+1}| \leq C\cdot|\epsilon_n|^2$, can be used to identify an interval around $\alpha$ for which convergence is guaranteed. Such convergence is termed *quadratic* (order 2). For floating point solutions, quadratic convergence and a well chosen initial point can lead to convergence in 4 or 5 iterations. In general, convergence is termed order $q$ when $|\epsilon_{n+1}| \approx C\cdot|\epsilon_n|^q$ + +* The term $-f''(\xi_n)/(2f'(\xi_n)$ indicates possible issues when $f''$ is too big near $\alpha$ or $f'$ is too small near $\alpha$. In particular if $f'(\alpha) = 0$, there need not be quadratic convergence, and convergence can take many iterations. A zero for which $f(x) = (x-\alpha)^{1+\beta}\cdot g(x)$, with $g(\alpha) \neq 0$ is called *simple* when $\beta=0$ and non-simple when $\beta > 0$. Newton's method is quadratic near *simple zeros* and need not be quadratic near *non-simple* zeros. +As well, if $f''$ is too big near $\alpha$, or $f'$ too small near $\alpha$, or $x_n$ too far from $\alpha$ (that is, $|\epsilon_n|>1$) the error might actually increase and convergence is not guaranteed. + +* The explicit form of the error function can be used to guarantee convergence for functions with a certain shape (monotonic, convex functions where the sign of $f''$ and $f'$ don't change). Quadratic convergence may only occur once the algorithm is near the zero. + +* The number of function evaluations per step for Newton's method is 2. + +---- + +```@docs +Roots.Newton +Roots.Halley +``` + +For non-simple zeros, Schroder showed an additional derivative can be used to yield quadratic convergence. + +```@docs +Roots.Schroder +``` + +## Derivative free methods + +The [secant](https://en.wikipedia.org/wiki/Secant_method) method replaces the derivative term in Newton's method with the slope of the secant line. + +$x_{n+1} = x_n - (\frac{f(x_n)-f(x_{n-1})}{x_n - x_{n-1}})^{-1}\cdot f(x_n).$ + +Though the secant method has convergence rate of order $\approx 1.618$ and is not quadratic, it +only requires one new function call per step so can be very effective. Often function evaluations are the slowest part of the computation and, as well, no derivative is needed. Because it can be very efficient, the secant method is used in the default method of `find_zero` when called with a single initial starting point. + +[Steffensen's](https://en.wikipedia.org/wiki/Steffensen%27s_method) method is a quadratially converging derivative free method which uses a secant line based on $x_n$ and $x_n + f(x_n)$. Though of higher order, it requires additional function calls per step and depends on a good initial starting value. Other derivative free methods are available, trading off increased function calls for higher-order convergence. They may be of interest when arbitrary precision is needed. A measure of efficiency is $q^{1/r}$ where $q$ is the order of convergence and $r$ the number of function calls per step. With this measure, the secant method would be $\approx (1.618)^{1/1}$ and Steffensen's would be less ($2^{1/2}$). + +---- + +```@docs +Order1 +Order2 +Order5 +Order8 +Order16 +``` + +As with Newton's method, convergence rates are for simple zeros. For non simple zeros there are related methods with varying convergence rates: + +```@docs +Roots.King +Roots.Esser +``` + + + +## Bracketing methods + +The [bisection](https://en.wikipedia.org/wiki/Bisection_method) identifies a zero of a *continuous* function bewteen $a$ and $b$ when $f(a)$ and $f(b)$ have different signs. (The interval $[a,b]$ is called a bracketing interval when $f(a)\cdot f(b) <0$.) The basaic alorithm is particularly simple, an interval $[a_i,b_i]$ is split at $c = (a_i+b_i)/2$. Either $f(c)=0$, or one of $[a_i,c]$ or $[c,b_i]$ is a bracketing interval, which is called $[a_{i+1},b_{i+1}]$. From this description, we see thaat $[a_i,b_i]$ has length $2^{-i}$ times the length of $[a_0,b_0]$, so the intervals will eventually terminate by finding a zero, $c$, or converge to a zero. This convergence is slow (the efficiency is only $1$, but guaranteed. For 64-bit floating point values, a reinterpretation of how the midpoint ($c$) is found leads to convergence is no more than $64$ iterations. + +In floating point, by guaranteed convergence we have either an exact zero or a bracketing interval consisting of two adjacent floating point values. When applied to *non*-continuous functions, this algorithm will identify an exact zero or a zero crossing of the function. (E.g., applied to $f(x)=1/x$ it will find $0$.) + +The default selection of midpoint described above includes no information about the function $f$ beyonds its sign. Algorithms exploiting the shape of the function can be significantly more efficient. The default bracketing method is due to [Alefeld, Potra, and Shi](https://dl.acm.org/doi/10.1145/210089.210111), and has efficiency $\approx 1.6686$. It is also used in the default method for `find_zero` when a single initial starting point is given if a bracketing interval is identified. + +---- + +```@docs +Bisection +Roots.A42 +Roots.AlefeldPotraShi +Roots.Brent +FalsePosition +``` + +## Hybrid methods + +A useful strategy is to begin with a non-bracketing method and switch to a bracketing method should a bracket be encoutered. This allows for the identification of zeros which are not surrounded by a bracket, and have guaranteed convergence should a bracket be encountered. Is is used by default by `find_zero(f,a)`. + +```@docs +Roots.Order0 +``` + +## Convergence + +Identifying when an algorithm converges or diverges requires specifications of tolerances and convergence criteria. + +In the case of exact bisection, convergence is mathematically +guaranteed. For floating point numbers, either an *exact* zero is +found, or the bracketing interval can be subdivided into $[a_n,b_n]$ +with $a_n$ and $b_n$ being adjacent floating point values. That is +$b_n-a_n$ is as small as possible in floating point numbers. This can +be considered a stopping criteria in $\Delta x$. For early termination +(less precision but fewer function calls) a tolerance can be given so +that if $\Delta_n=b_n-a_n$ is small enough the algorithm stops +successfully. In floating point assessing if $b_n \approx a_n$ +requires two tolerances: a *relative* tolerance, as the minimial +differences in floating point values depend on the size of $b_n$ and +$a_n$, and an absolute tolerancef or values near $0$. The valuese +`xrtol` anad `xatol` are passed to the `Base.isapprox` function to +determine this. + +Relying on the closeness of two $x$ values will not be adequate for +all problems, sa there are examples where the difference +$\Delta_n=|x_n-x_{n-1}|$ can be quite small, $0$ even, yet $f(x_n)$ is +not near a $0$. As such, for non-bracketing methods, a check on the +size of $f(x_n)$ is also used. As we find floating point +approximations to $\alpha$, the zero, we must consider values small +when $f(\alpha(1+\epsilon))$ is small. By Taylor's aapproximation, we +can expect this to be around +$\alpha\cdot \epsilon \cdot f'(\alpha)$. +That is, small depends on the size of $\alpha$ and the +derivative at $\alpha$. The former is handled by both relative and absolute +tolerances (`rtol` and `atol`). The size of $f'(\alpha)$ is problem +dependent, and can be accommodated by larger relative or absolute +tolerances. + +When an algorithm returns a `NaN` value, it terminates. This can happen near convergence or may indicate some issues. Early termination is checked for convergence in the size of $f(x_{n-1})$ with a relaxed tolerance when `strict=false` is specified (the default). + +!!! note "Relative tolerances and assessing $f(x) \approx 0$" + The use of relative tolerances to check if $f(x) \approx 0$ can lead to spurious answers where $x$ is very large (and hence the relative tolerance is large). The return of very large solutions should be checked against expectations of the answer. + + +Deciding if an algorithm won't terminate is done through counting the number or iterations performed or the number of function evaluations. These are adjusted through `maxevals` and `maxfnevals`. As most algorithms are superlinear, convergence happens rapidly near the answer, but all the algorithms can take a while to get near an answer, even when progress is made. As such, the valuese can indicate non-convergence by being too slow. On the other hand, leaving this too large can slow the determination. + + +Convergence criteria are method dependent and are determined by the `Roots.assess_convergence` methods. + + +```@docs +Roots.assess_convergence +``` + +Default tolerances are specified through the `Roots.default_tolerances` methods. + +```@docs +Roots.default_tolerances +``` + + + + +## Performance considerations + + +The abstractions and many checks for convergence employed by `find_zero` have a performance cost. When that is a critical concern, there are several "simple" methods provided which can offer significantly improved performaance. + +```@docs +Roots.secant_method +Roots.bisection +Roots.muller +Roots.newton +Roots.dfree +``` + +## Matlab interface + +The initial naming scheme used `fzero` instead of `fzeros`, following the name of the MATLAB function [fzero](https://www.mathworks.com/help/matlab/ref/fzero.html). This interface is not recommended, but, for now, still maintained. + +```@docs +Roots.fzero +``` + +!!! note + At one point there were technical reasons (specialization on functions) to have both `fzero` and `find_zero` interfaces, but that is no longer the case. + + + + + + diff --git a/doc/roots.md b/docs/src/roots.md similarity index 66% rename from doc/roots.md rename to docs/src/roots.md index a0ac1435..a3d4bd51 100644 --- a/doc/roots.md +++ b/docs/src/roots.md @@ -1,4 +1,4 @@ -# The Roots package +# An overview of `Roots` The `Roots` package contains simple routines for finding zeros of continuous scalar functions of a single real variable. A zero of $f$ @@ -8,9 +8,11 @@ function `find_zero`, which through multiple dispatch can handle many different In the following, we will use `Plots` for plotting and `ForwardDiff` to take derivatives. -``` -using Roots -using Plots, ForwardDiff; pyplot(); +```jldoctest roots +julia> using Roots + +julia> using Plots, ForwardDiff + ``` ## Bracketing @@ -33,19 +35,29 @@ To illustrate, consider the function $f(x) = \cos(x) - x$. From the graph we see readily that $[0,1]$ is a bracket (which we emphasize with an overlay): -```figure +```@example roots +using Plots, Roots f(x) = cos(x) - x plot(f, -2, 2) plot!([0,1], [0,0], linewidth=2) +savefig("plot-f-1.svg"); nothing #hide ``` +![](plot-f-1.svg) + The `Roots` package includes the bisection algorithm through `find_zero`. We use a vector or tuple to specify the initial condition and `Bisection()` to specify the algorithm: -``` -x = find_zero(f, (0, 1), Bisection()) # alternatively fzero(f, [0, 1]) -x, f(x) +```jldoctest roots +julia> f(x) = cos(x) - x +f (generic function with 1 method) + +julia> x = find_zero(f, (0, 1), Bisection()) # alternatively fzero(f, [0, 1]) +0.7390851332151607 + +julia> x, f(x) +(0.7390851332151607, 0.0) ``` For this function we see that `f(x)` is `0.0`. @@ -57,16 +69,24 @@ tells us that $[\pi/2, 3\pi/2]$ will be a bracket. In this call `Bisection()` is not specified, as it will be the default when the initial value is specified as a pair of numbers: -``` -f(x) = sin(x) -x = find_zero(f, (pi/2, 3pi/2)) -x, f(x) +```jldoctest roots +julia> f(x) = sin(x) +f (generic function with 1 method) + +julia> x = find_zero(f, (pi/2, 3pi/2)) +3.1415926535897936 + +julia> x, f(x) +(3.1415926535897936, -3.216245299353273e-16) + ``` This value of `x` does not exactly produce a zero, however, it is as close as can be: -``` -f(prevfloat(x)) * f(x) < 0.0 || f(x) * f(nextfloat(x)) < 0.0 +```jldoctest roots +julia> f(prevfloat(x)) * f(x) < 0.0 || f(x) * f(nextfloat(x)) < 0.0 +true + ``` That is, at `x` the function is changing sign. @@ -76,15 +96,19 @@ From a mathematical perspective, a zero is guaranteed for a continuity, it just looks for changes of sign. As such, the algorithm will identify discontinuities, not just zeros. For example: -``` -find_zero(x -> 1/x, (-1, 1)) +```jldoctest roots +julia> find_zero(x -> 1/x, (-1, 1)) +0.0 + ``` The endpoints and function values can even be infinite: -``` -find_zero(x -> Inf*sign(x), (-Inf, Inf)) # Float64 only +```jldoctest roots +julia> find_zero(x -> Inf*sign(x), (-Inf, Inf)) # Float64 only +0.0 + ``` @@ -92,8 +116,11 @@ The basic algorithm used for bracketing when the values are simple floating point values is a modification of the bisection method. For big float values, an algorithm due to Alefeld, Potra, and Shi is used. -``` -find_zero(sin, (big(3), big(4))) # uses a different algorithm then for (3,4) +```jldoctest roots +julia> find_zero(sin, (big(3), big(4))) # uses a different algorithm then for (3,4) +3.141592653589793238462643383279502884197169399375105820974944592307816406286198 + + ``` By default, bisection will converge to machine tolerance. This may @@ -102,9 +129,13 @@ terminate early, thereby utilizing fewer resources. For example, this uses 19 steps to reach accuracy to $10^{-6}$ (without specifying `xatol` it uses 51 steps): -``` -rt = find_zero(sin, (3.0, 4.0), xatol=1e-6) -rt - pi +```jldoctest roots +julia> rt = find_zero(sin, (3.0, 4.0), xatol=1e-6) +3.141592502593994 + +julia> rt - pi +-1.5099579897537296e-7 + ``` @@ -128,25 +159,42 @@ For example, the answer to our initial problem is visibly seen from a graph to be near 1. Given this, the zero is found through: -``` -f(x) = cos(x) - x -x = find_zero(f , 1) -x, f(x) +```jldoctest roots +julia> f(x) = cos(x) - x +f (generic function with 1 method) + + +julia> x = find_zero(f , 1) +0.7390851332151607 + +julia> x, f(x) +(0.7390851332151607, 0.0) + ``` For the polynomial $f(x) = x^3 - 2x - 5$, an initial guess of 2 seems reasonable: -``` -f(x) = x^3 - 2x - 5 -x = find_zero(f, 2) -x, f(x), sign(f(prevfloat(x)) * f(nextfloat(x))) +```jldoctest roots +julia> f(x) = x^3 - 2x - 5 +f (generic function with 1 method) + +julia> x = find_zero(f, 2) +2.0945514815423265 + +julia> x, f(x), sign(f(prevfloat(x)) * f(nextfloat(x))) +(2.0945514815423265, -8.881784197001252e-16, -1.0) + ``` For even more precision, `BigFloat` numbers can be used -``` -x = find_zero(sin, big(3)) -x, sin(x), x - pi +```jldoctest roots +julia> x = find_zero(sin, big(3)) +3.141592653589793238462643383279502884197169399375105820974944592307816406286198 + +julia> x, sin(x), x - pi +(3.141592653589793238462643383279502884197169399375105820974944592307816406286198, 1.096917440979352076742130626395698021050758236508687951179005716992142688513354e-77, 0.0) + ``` ### Higher order methods @@ -162,24 +210,40 @@ generally quite efficient. The even higher order ones are potentially useful when more precision is used. These algorithms are accessed by specifying the method after the initial starting point: -``` -f(x) = 2x - exp(-x) -x = find_zero(f, 1, Order1()) # also fzero(f, 1, order=1) -x, f(x) +```jldoctest roots +julia> f(x) = 2x - exp(-x) +f (generic function with 1 method) + +julia> x = find_zero(f, 1, Order1()) # also fzero(f, 1, order=1) +0.35173371124919584 + +julia> x, f(x) +(0.35173371124919584, 0.0) + ``` The above makes $8$ function calls, to the $57$ made with `Order0`. -``` -f(x) = (x + 3) * (x - 1)^2 -x = find_zero(f, -2, Order2()) -x, f(x) -``` +```jldoctest roots +julia> f(x) = (x + 3) * (x - 1)^2 +f (generic function with 1 method) +julia> x = find_zero(f, -2, Order2()) +-3.0 + +julia> x, f(x) +(-3.0, 0.0) ``` -x = find_zero(f, 2, Order8()) -x, f(x) + + +```jldoctest roots +julia> x = find_zero(f, 2, Order8()) +1.0000000027152591 + +julia> x, f(x) +(1.0000000027152591, 2.949052856287529e-17) + ``` The latter shows that zeros need not be simple zeros to be found. @@ -209,11 +273,19 @@ these are not exported, so must be prefixed with the package name to be used.) We can see how each works on a problem studied by Newton himself. Newton's method uses the function and its derivative: -``` -f(x) = x^3 - 2x - 5 -fp(x) = 3x^2 - 2 -x = Roots.newton(f, fp, 2) -x, f(x) +```jldoctest roots +julia> f(x) = x^3 - 2x - 5 +f (generic function with 1 method) + +julia> fp(x) = 3x^2 - 2 +fp (generic function with 1 method) + +julia> x = Roots.newton(f, fp, 2) +2.0945514815423265 + +julia> x, f(x) +(2.0945514815423265, -8.881784197001252e-16) + ``` To see the algorithm in progress, the argument `verbose=true` may be @@ -222,23 +294,31 @@ specified. Alternatively, `Roots.Newton()` can be specified as the method for `find_zero`. The functions are specified using a tuple: -``` -find_zero((f,fp), 2, Roots.Newton()) +```jldoctest roots +julia> find_zero((f,fp), 2, Roots.Newton()) +2.0945514815423265 + ``` The secant method typically needs two starting points, though a second one is computed if only one is give. Here we start with 2 and 3, specified through a tuple: -``` -x = Roots.secant_method(f, (2,3)) -x, f(x) +```jldoctest roots +julia> x = Roots.secant_method(f, (2,3)) +2.094551481542327 + +julia> x, f(x) +(2.094551481542327, 3.552713678800501e-15) + ``` Starting with a single point is also supported: -``` -Roots.secant_method(f, 2) +```jldoctest roots +julia> Roots.secant_method(f, 2) +2.0945514815423265 + ``` (This is like `Order1()`, but the implementation is significantly @@ -248,10 +328,16 @@ are used. This method can be used when speed is very important.) Halley's method has cubic convergence, as compared to Newton's quadratic convergence. It uses the second derivative as well: -``` -fpp(x) = 6x -x = Roots.halley(f, fp, fpp, 2) -x, f(x), sign(f(prevfloat(x)) * f(nextfloat(x))) +```jldoctest roots +julia> fpp(x) = 6x +fpp (generic function with 1 method) + +julia> x = Roots.halley(f, fp, fpp, 2) +2.0945514815423265 + +julia> x, f(x), sign(f(prevfloat(x)) * f(nextfloat(x))) +(2.0945514815423265, -8.881784197001252e-16, -1.0) + ``` (Halley's method takes 3 steps, Newton's 4, but Newton's uses 5 @@ -261,21 +347,30 @@ For many functions, their derivatives can be computed automatically. The `ForwardDiff` package provides a means. Here we define an operator `D` to compute a derivative: -``` -using ForwardDiff -D(f) = x -> ForwardDiff.derivative(f, float(x)) -D(f, n) = n > 1 ? D(D(f),n-1) : D(f) -``` +```jldoctest roots +julia> using ForwardDiff +julia> D(f) = x -> ForwardDiff.derivative(f, float(x)) +D (generic function with 1 method) + +julia> D(f, n) = n > 1 ? D(D(f),n-1) : D(f) +D (generic function with 2 methods) ``` -Roots.newton(f, D(f), 2) + + +```jldoctest roots +julia> Roots.newton(f, D(f), 2) +2.0945514815423265 + ``` Or, for Halley's method: -``` -Roots.halley(f, D(f), D(f,2), 2) +```jldoctest roots +julia> Roots.halley(f, D(f), D(f,2), 2) +2.0945514815423265 + ``` @@ -286,9 +381,13 @@ The `D` function, defined above, makes it straightforward to find critical point point of the function $f(x) = 1/x^2 + x^3, x > 0$ near $1.0$ is where the derivative is $0$ and can be found through: -``` -f(x) = 1/x^2 + x^3 -find_zero(D(f), 1) +```jldoctest roots +julia> f(x) = 1/x^2 + x^3 +f (generic function with 1 method) + +julia> find_zero(D(f), 1) +0.9221079114817278 + ``` For more complicated expressions, `D` will not work, and other means @@ -296,13 +395,15 @@ of finding a derivative can be employed. In this example, we have a function that models the flight of an arrow on a windy day: -``` -function flight(x, theta) - k = 1/2 - a = 200*cosd(theta) - b = 32/k - tand(theta)*x + (b/a)*x - b*log(a/(a-x)) -end +```jldoctest roots +julia> function flight(x, theta) + k = 1/2 + a = 200*cosd(theta) + b = 32/k + tand(theta)*x + (b/a)*x - b*log(a/(a-x)) + end +flight (generic function with 1 method) + ``` @@ -312,21 +413,31 @@ This can be solved for different `theta` with `find_zero`. In the following, we note that `log(a/(a-x))` will have an asymptote at `a`, so we start our search at `a-5`: -``` -function howfar(theta) - a = 200*cosd(theta) - find_zero(x -> flight(x, theta), a-5) -end +```jldoctest roots +julia> function howfar(theta) + a = 200*cosd(theta) + find_zero(x -> flight(x, theta), a-5) + end +howfar (generic function with 1 method) + ``` To visualize the trajectory if shot at 45 degrees, we have: -```figure +```@example roots +flight(x, theta) = (k = 1/2;a = 200*cosd(theta);b = 32/k;tand(theta)*x + (b/a)*x - b*log(a/(a-x))); nothing +howfar(theta) = (a = 200*cosd(theta);find_zero(x -> flight(x, theta), a-5)); nothing +howfarp(theta,h=1e-5) = (howfar(theta+h) - howfar(theta-h)) / (2h); nothing +tstar = find_zero(howfarp, 45); nothing # hide + theta = 45 plot(x -> flight(x, theta), 0, howfar(theta)) +savefig("flight.svg"); nothing # hide ``` +![](flight.svg) + To maximize the range we solve for the lone critical point of `howfar` within reasonable starting points. In this example, the derivative can not be taken automatically with @@ -334,19 +445,28 @@ within reasonable starting points. In this example, the derivative can not be ta search at 45 degrees--the angle which maximizes the trajectory on a non-windy day: -``` -h = 1e-5 -howfarp(theta) = (howfar(theta+h) - howfar(theta-h)) / (2h) -tstar = find_zero(howfarp, 45) +```jldoctest roots +julia> h = 1e-5 +1.0e-5 + +julia> howfarp(theta) = (howfar(theta+h) - howfar(theta-h)) / (2h) +howfarp (generic function with 1 method) + +julia> tstar = find_zero(howfarp, 45) +26.262308916287818 + ``` This graph shows the differences in the trajectories: -```figure +```@example roots plot(x -> flight(x, 45), 0, howfar(45)) plot!(x -> flight(x, tstar), 0, howfar(tstar)) +savefig("flight-2.svg"); nothing #hide ``` +![](flight-2.svg) + @@ -372,8 +492,10 @@ be quite different, as the next step generally tracks the intersection point of the tangent line. We see that starting at a $\pi/2$ causes this search to be problematic: -``` -find_zero(sin, pi/2, Order1()) +```jldoctest roots +julia> try find_zero(sin, pi/2, Order1()) catch err "Convergence failed" end +"Convergence failed" + ``` (Whereas, starting at `pi/2 + 0.3`--where the slope of the tangent @@ -382,16 +504,24 @@ is sufficiently close to point towards $\pi$--will find convergence at $\pi$.) For a classic example where a large second derivative is the issue, we have $f(x) = x^{1/3}$: -``` -f(x) = cbrt(x) -x = find_zero(f, 1, Order2()) # all of 2, 5, 8, and 16 fail or diverge towards infinity +```jldoctest roots +julia> f(x) = cbrt(x) +f (generic function with 1 method) + +julia> x = try find_zero(f, 1, Order2()) catch err "Convergence failed" end # all of 2, 5, 8, and 16 fail or diverge towards infinity +"Convergence failed" + ``` However, the default finds the root here, as a bracket is identified: -``` -x = find_zero(f, 1) -x, f(x) +```jldoctest roots +julia> x = find_zero(f, 1) +0.0 + +julia> x, f(x) +(0.0, 0.0) + ``` Finally, for many functions, all of these methods need a good initial @@ -399,25 +529,34 @@ guess. For example, the polynomial function $f(x) = x^5 - x - 1$ has its one zero near $1.16$. If we start far from it, convergence may happen, but it isn't guaranteed: -``` -f(x) = x^5 - x - 1 -x0 = 0.1 -find_zero(f, x0) +```jldoctest roots +julia> f(x) = x^5 - x - 1 +f (generic function with 1 method) + +julia> x0 = 0.1 +0.1 + +julia> try find_zero(f, x0) catch err "Convergence failed" end +"Convergence failed" + ``` Whereas, -``` -find_zero(f, x0, Order2()) +```jldoctest roots +julia> try find_zero(f, x0, Order2()) catch err "Convergence failed" end +"Convergence failed" + + ``` A graph shows the issue. We have overlayed 15 steps of Newton's method, the other algorithms being somewhat similar: -```figure,nocode +```@example roots using ForwardDiff D(f) = x -> ForwardDiff.derivative(f,float(x)) -xs = [x0] +xs = [0.1] # x0 n = 15 for i in 1:(n-1) push!(xs, xs[end] - f(xs[end])/D(f)(xs[end])) end ys = [zeros(Float64,n)';map(f, xs)'][1:2n] @@ -425,8 +564,11 @@ xs = xs[repeat(collect(1:n), inner=[2], outer=[1])] plot(f, -1.25, 1.5, linewidth=3, legend=false) plot!(zero, -1.25, 1.5, linewidth=3) plot!(xs, ys) +savefig("newton-15.svg"); nothing #hide ``` +![](newton-15.svg) + Though 15 steps are shown, only a few are discernible, as the function's relative maximum causes a trap for this algorithm. Starting to the right of the relative minimum--nearer the zero--would avoid this trap. The default @@ -446,15 +588,24 @@ x^2 + 270\cdot x^3 - 405\cdot x^4 + 243\cdot x^5$. Mathematically these are the same, however not so when evaluated in floating point. Here we look at the 21 floating point numbers near $1/3$: -``` -f(x) = (3x-1)^5 -f1(x) = -1 + 15*x - 90*x^2 + 270*x^3 - 405*x^4 + 243*x^5 -ns = [1/3]; -u=1/3; for i in 1:10 (u=nextfloat(u);push!(ns, u)) end -u=1/3; for i in 1:10 (u=prevfloat(u);push!(ns, u)) end -sort!(ns) +```jldoctest roots +julia> f(x) = (3x-1)^5 +f (generic function with 1 method) + +julia> f1(x) = -1 + 15*x - 90*x^2 + 270*x^3 - 405*x^4 + 243*x^5 +f1 (generic function with 1 method) + +julia> ns = [1/3]; + +julia> u=1/3; for i in 1:10 (global u=nextfloat(u);push!(ns, u)) end + +julia> u=1/3; for i in 1:10 (global u=prevfloat(u);push!(ns, u)) end + +julia> sort!(ns); + +julia> maximum(abs.(f.(ns) - f1.(ns))) +1.887379141862766e-15 -maximum(abs.(f.(ns) - f1.(ns))) ``` We see the function values are close for each point, as the maximum difference @@ -468,20 +619,80 @@ small differences might matter. Here we look at the signs of the function values: -``` -fs = sign.(f.(ns)) -f1s = sign.(f1.(ns)) -[ns-1/3 fs f1s] +```jldoctest roots +julia> fs = sign.(f.(ns)); + +julia> f1s = sign.(f1.(ns)); + +julia> [ns.-1/3 fs f1s] +21×3 Array{Float64,2}: + -5.55112e-16 -1.0 -1.0 + -4.996e-16 -1.0 -1.0 + -4.44089e-16 -1.0 -1.0 + -3.88578e-16 -1.0 1.0 + -3.33067e-16 -1.0 1.0 + -2.77556e-16 -1.0 1.0 + -2.22045e-16 -1.0 -1.0 + -1.66533e-16 -1.0 -1.0 + -1.11022e-16 -1.0 1.0 + -5.55112e-17 -1.0 1.0 + ⋮ + 1.11022e-16 1.0 1.0 + 1.66533e-16 1.0 1.0 + 2.22045e-16 1.0 -1.0 + 2.77556e-16 1.0 -1.0 + 3.33067e-16 1.0 1.0 + 3.88578e-16 1.0 1.0 + 4.44089e-16 1.0 1.0 + 4.996e-16 1.0 1.0 + 5.55112e-16 1.0 0.0 + ``` Parsing this shows a few surprises. First, there are two zeros of `f(x)` identified--not just one as expected mathematically--the floating point value of `1/3` and the next largest floating point -number. For `f1(x)` there is only one zero, but it isn't the floating +number. + +```jldoctest roots +julia> findall(iszero, fs) +2-element Array{Int64,1}: + 11 + 12 +``` + + + +For `f1(x)` there is only one zero, but it isn't the floating point value for `1/3` but rather 10 floating point numbers -away. Further, there are 5 sign changes of the function values. There -is no guarantee that a zero will be present, but for a mathematical -function that changes sign, there will be at least one sign change. +away. + + +```jldoctest roots +julia> findall(iszero, f1s) +1-element Array{Int64,1}: + 21 +``` + + + +Further, there are several sign changes of the function values for `f1s`: + +```jldoctest roots +julia> findall(!iszero,diff(sign.(f1s))) +6-element Array{Int64,1}: + 3 + 6 + 8 + 14 + 16 + 20 + +``` + +There is no guarantee that a zero will be present, but for a +mathematical function that changes sign, there will be at least one +sign change. With this in mind, an exact zero of `f` would be either where `iszero(f(x))` is true *or* where the function has a sign change (either `f(x)*f(prevfloat(x))<0` or `f(x)*f(nextfloat(x)) < 0`). @@ -495,26 +706,40 @@ these conditions. Now consider the function `f(x) = exp(x)-x^4`. The value`x=8.613169456441398` is a zero in this sense, as there is a change of sign: -``` -f(x) = exp(x) - x^4 -F(x) = sign(f(x)) -x=8.613169456441398 -F(prevfloat(x)), F(x), F(nextfloat(x)) +```jldoctest roots +julia> f(x) = exp(x) - x^4 +f (generic function with 1 method) + +julia> F(x) = sign(f(x)) +F (generic function with 1 method) + +julia> x=8.613169456441398 +8.613169456441398 + +julia> F(prevfloat(x)), F(x), F(nextfloat(x)) +(-1.0, -1.0, 1.0) + ``` However, the value of `f(x)` is not as small as one might initially expect for a zero: -``` -f(x) +```jldoctest roots +julia> f(x), abs(f(x)/eps(x)) +(-2.7284841053187847e-12, 1536.0) + ``` The value `x` is an approximation to the actual mathematical zero, call it $x$. There is a difference between $f(x)$ (the mathematical answer) and `f(x)` (the floating point answer). Roughly speaking we expect `f(x)` to be about $f(x) + f'(x)\cdot \delta$, where $\delta$ is the difference between `x` and $x$. This will be on the scale of `abs(x) * eps()`, so all told we expect an answer to be in the range of $0$ plus or minus this value: -``` -fp(x) = exp(x) - 4x^3 # the derivative -fp(x) * abs(x) * eps() +```jldoctest roots +julia> fp(x) = exp(x) - 4x^3 # the derivative +fp (generic function with 1 method) + +julia> fp(x) * abs(x) * eps() +5.637565490466956e-12 + ``` which is about what we see. @@ -546,8 +771,10 @@ One issue with relative tolerances is that for functions with sublinear growth, extremely large values will be considered zeros. Returning to an earlier example, we have a misidentified zero: -``` -find_zero(cbrt, 1, Order8()) +```jldoctest roots +julia> find_zero(cbrt, 1, Order8()) +2.0998366730115564e23 + ``` For `Order8`, the algorithm rapidly marches off towards infinity so the relative @@ -587,59 +814,82 @@ The methods described above are used to identify one of possibly several zeros. The `find_zeros` function searches the interval $(a,b)$ for all zeros of a function $f$. It is straightforward to use: -``` -f(x) = exp(x) - x^4 -a, b = -10, 10 -zs = find_zeros(f, a, b) +```jldoctest roots +julia> f(x) = exp(x) - x^4 +f (generic function with 1 method) + +julia> a, b = -10, 10 +(-10, 10) + +julia> zs = find_zeros(f, a, b) +3-element Array{Float64,1}: + -0.8155534188089606 + 1.4296118247255556 + 8.613169456441398 + ``` The search interval, $(a,b)$, is specified through two arguments. It is assumed that neither endpoint is a zero. Here we see the result of the search graphically: -``` +```@example roots +f(x) = exp(x) - x^4; nothing +a,b=-10,10; nothing +zs = find_zeros(f, a, b); nothing plot(f, a, b) scatter!(zs, f.(zs)) +savefig("plot-f-2.svg"); nothing #hide ``` +![](plot-f-2.svg) + + We can identify points where the first and second derivative is zero. We use `D` from above: -``` +```@example roots f(x) = cos(x) + cos(2x) a, b = -10, 10 cps = find_zeros(D(f), a, b) -ips = find_zeros(D(f,2), a, b) +ips = find_zeros((D∘D)(f), a, b) plot(f, a, b) scatter!(cps, f.(cps)) scatter!(ips, f.(ips), markercolor = :yellow) +savefig("plot-f-3.svg"); nothing ``` +![](plot-f-3.svg) + + The `find_zeros` algorithm will use bisection when a bracket is identified. This method will identify jumps, so areas where the derivative changes sign (and not necessarily a zero of the derivative) will typically be identified: -``` +```@example roots f(x) = abs(cbrt(x^2-1)) a, b = -5, 5 cps = find_zeros(D(f), a, b) plot(f, a, b) scatter!(cps, f.(cps)) +savefig("plot-f-4.svg"); nothing ``` +![](plot-f-4.svg) + In this example, the derivative has vertical asymptotes at $x=1$ and $x=-1$ so is not continuous there. The bisection method identifies the zero crossing, not a zero. - +---- The search for all zeros in an interval is confounded by a few things: * too many zeros in the interval $(a,b)$ -* nearby zeros +* nearby zeros ("nearby" depends on the size of $(a,b)$ as well should this be very wide) The algorithm is adaptive, so that it can succeed when there are many zeros, but it may be necessary to increase `no_pts` from the default @@ -647,33 +897,45 @@ of 12, at the cost of possibly taking longer for the search. Here the algorithm identifies all the zeros, despite there being several: -``` +```@example roots f(x) = cos(x)^2 + cos(x^2) a, b = 0, 10 rts = find_zeros(f, a, b) plot(f, a, b) scatter!(rts, f.(rts)) +savefig("plot-f-4a.svg"); nothing ``` +![](plot-f-4a.svg) + + For nearby zeros, the algorithm does pretty well, though it isn't perfect. Here we see for $f(x) = \sin(1/x)$--with infinitely many zeros around $0$--it finds many: -``` +```@example roots f(x) = iszero(x) ? NaN : sin(1/x) # avoid sin(Inf) error rts = find_zeros(f, -1, 1) # 88 zeros identified plot(f, -1, 1) scatter!(rts, f.(rts)) +savefig("plot-f-5.svg"); nothing ``` +![](plot-f-5.svg) + The function, $f(x) = (x-0.5)^3 \cdot (x-0.499)^3$, looks *too* much like $g(x) = x^6$ to `find_zeros` for success, as the two zeros are very nearby: -``` -f(x) = (x-0.5)^3 * (x-0.499)^3 -find_zeros(f, 0, 1) +```jldoctest roots +julia> f(x) = (x-0.5)^3 * (x-0.499)^3 +f (generic function with 1 method) + +julia> find_zeros(f, 0, 1) +1-element Array{Float64,1}: + 0.5 + ``` The issue here isn't *just* that the algorithm can't identify zeros @@ -682,17 +944,30 @@ nearby values approximately zero. The algorithm will have success when the powers are smaller -``` -f(x) = (x-0.5)^2 * (x-0.499)^2 -find_zeros(f, 0, 1) +```jldoctest roots +julia> f(x) = (x-0.5)^2 * (x-0.499)^2 +f (generic function with 1 method) + +julia> find_zeros(f, 0, 1) +2-element Array{Float64,1}: + 0.49899999999999994 + 0.5 + ``` It can have success for closer pairs of zeros: -``` -f(x) = (x-0.5) * (x - 0.49999) -find_zeros(f, 0, 1) +```jldoctest roots +julia> f(x) = (x-0.5) * (x - 0.49999) +f (generic function with 1 method) + +julia> find_zeros(f, 0, 1) +2-element Array{Float64,1}: + 0.49999 + 0.5 + ``` Combinations of large (even) multiplicity zeros or very nearby -zeros, can lead to misidentification. +zeros, can lead to misidentification. + diff --git a/src/bracketing.jl b/src/bracketing.jl index 9eaf162c..536f27f7 100644 --- a/src/bracketing.jl +++ b/src/bracketing.jl @@ -19,6 +19,7 @@ abstract type AbstractBisection <: AbstractBracketing end """ Bisection() + Roots.BisectionExact() If possible, will use the bisection method over `Float64` values. The bisection method starts with a bracketing interval `[a,b]` and splits @@ -26,7 +27,8 @@ it into two intervals `[a,c]` and `[c,b]`, If `c` is not a zero, then one of these two will be a bracketing interval and the process continues. The computation of `c` is done by `_middle`, which reinterprets floating point values as unsigned integers and splits -there. This method avoids floating point issues and when the +there. It was contributed by [Jason Merrill](https://gist.github.com/jwmerrill/9012954). +This method avoids floating point issues and when the tolerances are set to zero (the default) guarantees a "best" solution (one where a zero is found or the bracketing interval is of the type `[a, nextfloat(a)]`). @@ -36,7 +38,7 @@ is approximately equal to an endpoint using absolute tolerance `xatol` and relative tolerance `xrtol`. When a zero tolerance is given and the values are not `Float64` -values, this will call the `A42` method. +values, this will call the [`A42`](@ref) method. """ @@ -163,7 +165,7 @@ end # for Bisection, the defaults are zero tolerances and strict=true """ - default_tolerances(M, [T], [S]) + default_tolerances(M::Bisection, [T], [S]) For `Bisection` (or `BisectionExact`), when the `x` values are of type `Float64`, `Float32`, @@ -173,7 +175,7 @@ algorithm is guaranteed to converge to an exact zero, or a point where the function changes sign at one of the answer's adjacent floating point values. -For other types, the the `A42` method (with its tolerances) is used. +For other types, the [`A42`](@ref) method (with its tolerances) is used. """ default_tolerances(M::Union{Bisection, BisectionExact}) = default_tolerances(M,Float64, Float64) @@ -365,10 +367,10 @@ abstract type AbstractAlefeldPotraShi <: AbstractBracketing end Bracketing method which finds the root of a continuous function within a provided interval [a, b], without requiring derivatives. It is based -on algorithm 4.2 described in: 1. G. E. Alefeld, F. A. Potra, and +on algorithm 4.2 described in: G. E. Alefeld, F. A. Potra, and Y. Shi, "Algorithm 748: enclosing zeros of continuous functions," ACM -Trans. Math. Softw. 21, 327–344 (1995), DOI: 10.1145/210089.210111. -Originally by John Travers +Trans. Math. Softw. 21, 327–344 (1995), DOI: [10.1145/210089.210111](https://doi.org/10.1145/210089.210111). +Originally by John Travers. """ struct A42 <: AbstractAlefeldPotraShi end @@ -703,10 +705,9 @@ end Follows algorithm in "ON ENCLOSING SIMPLE ROOTS OF NONLINEAR EQUATIONS", by Alefeld, Potra, Shi; DOI: -10.1090/S0025-5718-1993-1192965-2 -[link](http://www.ams.org/journals/mcom/1993-61-204/S0025-5718-1993-1192965-2/S0025-5718-1993-1192965-2.pdf). Efficiency -is 1.618. Less efficient, but can be faster than A42() method. - +[10.1090/S0025-5718-1993-1192965-2](https://doi.org/10.1090/S0025-5718-1993-1192965-2). + Efficiency is 1.618. Less efficient, but can be faster than the [`A42`](@ref) method. +Originally by John Travers. """ struct AlefeldPotraShi <: AbstractAlefeldPotraShi end @@ -897,6 +898,7 @@ end ## ---------------------------- +struct FalsePosition{R} <: AbstractBisection end """ FalsePosition() @@ -928,7 +930,7 @@ Examples find_zero(x -> x^5 - x - 1, (-2, 2), FalsePosition()) ``` """ -struct FalsePosition{R} <: AbstractBisection end +FalsePosition FalsePosition(x=:anderson_bjork) = FalsePosition{x}() function update_state(method::FalsePosition, fs, o::UnivariateZeroState{T,S}, options::UnivariateZeroOptions) where {T,S} diff --git a/src/derivative_free.jl b/src/derivative_free.jl index 7ddca156..2f610300 100644 --- a/src/derivative_free.jl +++ b/src/derivative_free.jl @@ -104,9 +104,9 @@ step fails to decrease the function value, a quadratic step is used up to 4 times. This is not really 0-order: the secant method has order -1.6...[https://en.wikipedia.org/wiki/Secant_method#Comparison_with_other_root-finding_methods] +1.6...[Wikipedia](https://en.wikipedia.org/wiki/Secant_method#Comparison_with_other_root-finding_methods_ and the the bracketing method has order -1.6180...[http://www.ams.org/journals/mcom/1993-61-204/S0025-5718-1993-1192965-2/S0025-5718-1993-1192965-2.pdf] +1.6180...[Wikipedia](http://www.ams.org/journals/mcom/1993-61-204/S0025-5718-1993-1192965-2/S0025-5718-1993-1192965-2.pdf) so for reasonable starting points, this algorithm should be superlinear, and relatively robust to non-reasonable starting points. @@ -138,8 +138,8 @@ updated point is the intersection point of x axis with the secant line formed from the two points. The secant method uses 1 function evaluation per step and has order `(1+sqrt(5))/2`. -The error, `e_n = x_n - alpha`, satisfies -`e2 = f[x1,x0,alpha] / f[x1,x0] * (x1-alpha) * (x0 - alpha)`. +The error, `eᵢ = xᵢ - α`, satisfies +`eᵢ₊₂ = f[xᵢ₊₁,xᵢ,α] / f[xᵢ₊₁,xᵢ] * (xᵢ₊₁-α) * (xᵢ - α)`. """ struct Secant <: AbstractSecant end @@ -184,12 +184,12 @@ to `f/f'`. However, this uses `f' ~ fp = (fx - f(x-fx))/fx` (a Steffensen step) this implementation, `Order1B`, when `fx` is too big, a single secant step of `f` is used. -The *asymptotic* error, `e_n = x_n - alpha`, is given by -`e2 = 1/2⋅G''/G'⋅ e0⋅e1 + (1/6⋅G'''/G' - (1/2⋅G''/G'))^2⋅e0⋅e1⋅(e0+e1)`. +The *asymptotic* error, `eᵢ = xᵢ - α`, is given by +`eᵢ₊₂ = 1/2⋅G''/G'⋅ eᵢ⋅eᵢ₊₁ + (1/6⋅G'''/G' - (1/2⋅G''/G'))^2⋅eᵢ⋅eᵢ₊₁⋅(eᵢ+eᵢ₊₁)`. """ -struct Order1B <: AbstractSecant end struct King <: AbstractSecant end +struct Order1B <: AbstractSecant end function update_state(method::Order1B, fs, o::UnivariateZeroState{T,S}, options) where {T, S} @@ -268,8 +268,8 @@ poor initial guesses when `f(x)` is large, due to how `f'(x)` is approximated. This algorithm, `Order2`, replaces a Steffensen step with a secant step when `f(x)` is large. -The error, `e_n - alpha`, satisfies -`e1 = f[x0, x+f0, alpha] / f[x0,x0+f0] ⋅ (1 - f[x0,alpha] ⋅ e0^2` +The error, `eᵢ - α`, satisfies +`eᵢ₊₁ = f[xᵢ, xᵢ+fᵢ, α] / f[xᵢ,xᵢ+fᵢ] ⋅ (1 - f[xᵢ,α] ⋅ eᵢ²` """ struct Order2 <: AbstractSecant end struct Steffensen <: AbstractSecant end @@ -320,7 +320,7 @@ zero. Schroder's method has update step `x - r2/(r2-r1) * r1`, where `ri = f^(i-1)/f^(i)`. Esser approximates `f' ~ f[x-h, x+h], f'' ~ f[x-h,x,x+h]`, where `h = fx`, as with Steffensen's method, Requiring 3 function calls per step. The implementation `Order2B` uses a secant -step when |fx| is considered too large. +step when `|fx|` is considered too large. Esser, H. Computing (1975) 14: 367. https://doi.org/10.1007/BF02253547 @@ -338,8 +338,8 @@ find_zero(g, x0, Order2(), verbose=true) # 22 / 45 find_zero(g, x0, Roots.Order2B(), verbose=true) # 4 / 10 ``` """ -struct Order2B <: AbstractSecant end struct Esser <: AbstractSecant end +struct Order2B <: AbstractSecant end function update_state(method::Order2B, fs, o::UnivariateZeroState{T,S}, options) where {T, S} update_state_guarded(method, Secant(), Esser(), fs, o, options) @@ -400,11 +400,11 @@ end Implements an order 5 algorithm from *A New Fifth Order Derivative Free Newton-Type Method for Solving Nonlinear Equations* by Manoj Kumar, Akhilesh Kumar Singh, and Akanksha, Appl. Math. Inf. Sci. 9, -No. 3, 1507-1513 (2015), DOI: 10.12785/amis/090346. Four function +No. 3, 1507-1513 (2015), DOI: [10.12785/amis/090346](https://doi.org/10.12785/amis/090346). Four function calls per step are needed. -The error, `e_n = x_n - alpha`, satisfies -`e1 = K_1 ⋅ K_5 ⋅ M ⋅ e0^5 + O(e0^6)` +The error, `eᵢ = xᵢ - α`, satisfies +`eᵢ₊₁ = K₁ ⋅ K₅ ⋅ M ⋅ eᵢ⁵ + O(eᵢ⁶)` """ struct Order5 <: AbstractSecant end @@ -515,10 +515,10 @@ Implements an eighth-order algorithm from *New Eighth-Order Derivative-Free Methods for Solving Nonlinear Equations* by Rajinder Thukral, International Journal of Mathematics and Mathematical Sciences Volume 2012 (2012), Article ID 493456, 12 pages DOI: -10.1155/2012/493456. Four function calls per step are required. +[10.1155/2012/493456](https://doi.org/10.1155/2012/493456). Four function calls per step are required. -The error, `e_n = x_n - alpha`, is expressed as `e1 = K ⋅ e0^8` in -(2.25) of the paper for an explicit K. +The error, `eᵢ = xᵢ - α`, is expressed as `eᵢ₊₁ = K ⋅ eᵢ⁸` in +(2.25) of the paper for an explicit `K`. """ struct Order8 <: AbstractSecant end @@ -610,8 +610,8 @@ this method generally isn't faster (fewer function calls/steps) over other methods when using `Float64` values, but may be useful for solving over `BigFloat`. -The error, `e_n = x_n - alpha`, is expressed as `e1 = K -e_0^16` for an explicit `K` in equation (50) of the paper. +The error, `eᵢ = xᵢ - α`, is expressed as `eᵢ₊₁ = K⋅eᵢ¹⁶` for an explicit `K` +in equation (50) of the paper. """ struct Order16 <: AbstractSecant end diff --git a/src/find_zero.jl b/src/find_zero.jl index a34f7ae9..de80cd20 100644 --- a/src/find_zero.jl +++ b/src/find_zero.jl @@ -151,7 +151,7 @@ mutable struct UnivariateZeroOptions{Q,R,S,T} end """ - default_tolerances(Method, [T], [S]) + default_tolerances(M::AbstractUnivariateZeroMethod, [T], [S]) The default tolerances for most methods are `xatol=eps(T)`, `xrtol=eps(T)`, `atol=4eps(S)`, and `rtol=4eps(S)`, with the proper @@ -159,8 +159,7 @@ units (absolute tolerances have the units of `x` and `f(x)`; relative tolerances are unitless). For `Complex{T}` values, `T` is used. The number of iterations is limited by `maxevals=40`, the number of -function evaluations is not capped, due to `maxfnevals=typemax(Int)`, -and `strict=false`. +function evaluations is not capped. """ default_tolerances(M::AbstractUnivariateZeroMethod) = default_tolerances(M, Float64, Float64) @@ -427,7 +426,7 @@ end """ - find_zero(fs, x0, method; kwargs...) + find_zero(fs, x0, M, [N::AbstractBracketing]; kwargs...) Interface to one of several methods for find zeros of a univariate function. @@ -481,19 +480,18 @@ convergence. See the help page for `Roots.default_tolerances(method)` for details on the default tolerances. In general, with floating point numbers, convergence must be -understood as not an absolute statement. Even if mathematically x is +understood as not an absolute statement. Even if mathematically α is an answer and xstar the floating point realization, it may be that -f(xstar) - f(x) = f(xstar) ≈ f'(x) ⋅ eps(x), so tolerances must be +`f(xstar) - f(α) ≈ xstar ⋅ f'(α) ⋅ eps(α)`, so tolerances must be appreciated, and at times specified. For the `Bisection` methods, convergence is guaranteed, so the tolerances are set to be 0 by default. -If a bracketing method is passed in after the method specification, if a bracket is found, the bracketing method will used to identify the zero. This is what `Order0` does by default, with a secant step initially. +If a bracketing method is passed in after the method specification, when a bracket is found, the bracketing method will used to identify the zero. This is what `Order0` does by default, with a secant step initially and the `A42` method when a bracket is encountered. Note: The order of the method is hinted at in the naming scheme. A -scheme is order `q` if, with `e_n = x_n - alpha`, `e_{n+1} = C -e_n^q`. If the error `e_n` is small enough, then essentially the error -will gain `q` times as many leading zeros each step. However, if the +scheme is order `r` if, with `eᵢ = xᵢ - α`, `eᵢ₊₁ = C⋅eᵢʳ`. If the error `eᵢ` is small enough, then essentially the error +will gain `r` times as many leading zeros each step. However, if the error is not small, this will not be the case. Without good initial guesses, a high order method may still converge slowly, if at all. The `OrderN` methods have some heuristics employed to ensure a wider range @@ -502,32 +500,148 @@ though those are available through unexported methods. # Examples: +Default methods. + +```jldoctest find_zero +julia> using Roots + +julia> find_zero(sin, 3) # use Order0() +3.141592653589793 + +julia> find_zero(sin, (3,4)) # use Bisection() +3.1415926535897936 +``` + +Specifying a method, + +```jldoctest find_zero +julia> find_zero(sin, (3,4), Order1()) # can specify two starting points for secant method +3.141592653589793 + +julia> find_zero(sin, 3.0, Order2()) # Use Steffensen method +3.1415926535897936 + +julia> find_zero(sin, big(3.0), Order16()) # rapid convergence +3.141592653589793238462643383279502884197169399375105820974944592307816406286198 + +julia> find_zero(sin, (3, 4), Roots.A42()()) # fewer function calls than Bisection(), in this case +ERROR: MethodError: objects of type Roots.A42 are not callable +Stacktrace: + [1] top-level scope at REPL[12]:1 + +julia> find_zero(sin, (3, 4), FalsePosition(8)) # 1 of 12 possible algorithms for false position +3.141592653589793 + +julia> find_zero((sin,cos), 3.0, Roots.Newton()) # use Newton's method +3.141592653589793 + +julia> find_zero((sin, cos, x->-sin(x)), 3.0, Roots.Halley()) # use Halley's method +3.141592653589793 + ``` -# default methods -find_zero(sin, 3) # use Order0() -find_zero(sin, (3,4)) # use Bisection() - -# specifying a method -find_zero(sin, (3,4), Order1()) # can specify two starting points for secant method -find_zero(sin, 3.0, Order2()) # Use Steffensen method -find_zero(sin, big(3.0), Order16()) # rapid convergence -find_zero(sin, (3, 4), Roots.A42()()) # fewer function calls than Bisection(), in this case -find_zero(sin, (3, 4), FalsePosition(8)) # 1 of 12 possible algorithms for false position -find_zero((sin,cos), 3.0, Roots.Newton()) # use Newton's method -find_zero((sin, cos, x->-sin(x)), 3.0, Roots.Halley()) # use Halley's method - -# changing tolerances -fn, x0, xstar = (x -> (2x*cos(x) + x^2 - 3)^10/(x^2 + 1), 3.0, 2.9806452794385368) -find_zero(fn, x0, Order2()) - xstar # 0.014079847201995843 -find_zero(fn, x0, Order2(), atol=0.0, rtol=0.0) # error: x_n ≉ x_{n-1}; just f(x_n) ≈ 0 -fn, x0, xstar = (x -> (sin(x)*cos(x) - x^3 + 1)^9, 1.0, 1.117078770687451) -find_zero(fn, x0, Order2()) # 1.1122461983100858 -find_zero(fn, x0, Order2(), maxevals=3) # Roots.ConvergenceFailed: 26 iterations needed - -# tracing output -find_zero(x->sin(x), 3.0, Order2(), verbose=true) # 3 iterations -find_zero(x->sin(x)^5, 3.0, Order2(), verbose=true) # 22 iterations -find_zero(x->sin(x)^5, 3.0, Roots.Order2B(), verbose=true) # 2 iterations + +Changing tolerances. + +```jldoctest find_zero +julia> fn = x -> (2x*cos(x) + x^2 - 3)^10/(x^2 + 1); + +julia> x0, xstar = 3.0, 2.9947567209477; + +julia> find_zero(fn, x0, Order2()) ≈ xstar +true + +julia> find_zero(fn, x0, Order2(), atol=0.0, rtol=0.0) # error: x_n ≉ x_{n-1}; just f(x_n) ≈ 0 +ERROR: Roots.ConvergenceFailed("Stopped at: xn = 2.991488255523429") +Stacktrace: + [1] find_zero(::Function, ::Float64, ::Order2, ::Nothing; tracks::Roots.NullTracks, verbose::Bool, kwargs::Base.Iterators.Pairs{Symbol,Float64,Tuple{Symbol,Symbol},NamedTuple{(:atol, :rtol),Tuple{Float64,Float64}}}) at /Users/verzani/julia/Roots/src/find_zero.jl:670 + [2] top-level scope at REPL[12]:1 + +julia> fn = x -> (sin(x)*cos(x) - x^3 + 1)^9; + +julia> x0, xstar = 1.0, 1.112243913023029; + +julia> find_zero(fn, x0, Order2()) ≈ xstar +true + +julia> find_zero(fn, x0, Order2(), maxevals=3) # Roots.ConvergenceFailed: 26 iterations needed, not 3 +ERROR: Roots.ConvergenceFailed("Stopped at: xn = 1.0482748172022405") +Stacktrace: + [1] find_zero(::Function, ::Float64, ::Order2, ::Nothing; tracks::Roots.NullTracks, verbose::Bool, kwargs::Base.Iterators.Pairs{Symbol,Int64,Tuple{Symbol},NamedTuple{(:maxevals,),Tuple{Int64}}}) at /Users/verzani/julia/Roots/src/find_zero.jl:670 + [2] top-level scope at REPL[12]:1 +``` + +Tracing output. + +```jldoctest find_zero +julia> find_zero(x->sin(x), 3.0, Order2(), verbose=true) # 3 iterations +Results of univariate zero finding: + +* Converged to: 3.1415926535897936 +* Algorithm: Order2() +* iterations: 2 +* function evaluations: 5 +* stopped as |f(x_n)| ≤ max(δ, max(1,|x|)⋅ϵ) using δ = atol, ϵ = rtol + +Trace: +x_0 = 3.0000000000000000, fx_0 = 0.1411200080598672 +x_1 = 3.1425464815525403, fx_1 = -0.0009538278181169 +x_2 = 3.1415926535897936, fx_2 = -0.0000000000000003 + +3.1415926535897936 + +julia> find_zero(x->sin(x)^5, 3.0, Order2(), verbose=true) # 22 iterations +Results of univariate zero finding: + +* Converged to: 3.140534939851113 +* Algorithm: Order2() +* iterations: 22 +* function evaluations: 46 +* stopped as |f(x_n)| ≤ max(δ, max(1,|x|)⋅ϵ) using δ = atol, ϵ = rtol + +Trace: +x_0 = 3.0000000000000000, fx_0 = 0.0000559684091879 +x_1 = 3.0285315910604353, fx_1 = 0.0000182783542076 +x_2 = 3.0512479368872216, fx_2 = 0.0000059780426727 +x_3 = 3.0693685883136541, fx_3 = 0.0000019566875137 +x_4 = 3.0838393517913989, fx_4 = 0.0000006407325974 +x_5 = 3.0954031275790856, fx_5 = 0.0000002098675747 +x_6 = 3.1046476918938040, fx_6 = 0.0000000687514870 +x_7 = 3.1120400753639790, fx_7 = 0.0000000225247921 +x_8 = 3.1179523212360416, fx_8 = 0.0000000073801574 +x_9 = 3.1226812716693950, fx_9 = 0.0000000024181703 +x_10 = 3.1264639996586729, fx_10 = 0.0000000007923528 +x_11 = 3.1294899615147704, fx_11 = 0.0000000002596312 +x_12 = 3.1319106162503414, fx_12 = 0.0000000000850746 +x_13 = 3.1338470835729701, fx_13 = 0.0000000000278769 +x_14 = 3.1353962361189192, fx_14 = 0.0000000000091346 +x_15 = 3.1366355527270868, fx_15 = 0.0000000000029932 +x_16 = 3.1376269806673180, fx_16 = 0.0000000000009808 +x_17 = 3.1384199603056921, fx_17 = 0.0000000000003215 +x_18 = 3.1390543962469541, fx_18 = 0.0000000000001054 +x_19 = 3.1395625842920500, fx_19 = 0.0000000000000345 +x_20 = 3.1399667213451634, fx_20 = 0.0000000000000114 +x_21 = 3.1402867571209034, fx_21 = 0.0000000000000038 +x_22 = 3.1405349398511131, fx_22 = 0.0000000000000013 + +3.140534939851113 + +julia> find_zero(x->sin(x)^5, 3.0, Roots.Order2B(), verbose=true) # 2 iterations +Results of univariate zero finding: + +* Converged to: 3.1397074174874358 +* Algorithm: Roots.Order2B() +* iterations: 2 +* function evaluations: 7 +* Note: Estimate for multiplicity had issues. + Algorithm stopped early, but |f(xn)| < ϵ^(1/3), where ϵ depends on xn, rtol, and atol. + +Trace: +x_0 = 3.0000000000000000, fx_0 = 0.0000559684091879 +x_1 = 3.1397074174874358, fx_1 = 0.0000000000000238 +x_2 = 3.1397074174874358, fx_2 = 0.0000000000000238 + +3.1397074174874358 + ``` """ function find_zero(fs, x0, method::AbstractUnivariateZeroMethod, diff --git a/src/find_zeros.jl b/src/find_zeros.jl index e497c0c2..0caf47fb 100644 --- a/src/find_zeros.jl +++ b/src/find_zeros.jl @@ -138,42 +138,91 @@ end """ - find_zeros(f, a, b; [no_pts=12, k=8, naive=false, xatol, xrtol, atol, rtol]) + find_zeros(f, a, b; [no_pts=12, k=8, naive=false, xatol, xrtol, atol, rtol]) -Search for zeros of f in the interval [a,b]. +Search for zeros of `f` in the interval `[a,b]`. # Examples -```julia-repl -find_zeros(x -> exp(x) - x^4, -5, 20) # a few well-spaced zeros -find_zeros(x -> sin(x^2) + cos(x)^2, 0, 10) # many zeros -find_zeros(x -> cos(x) + cos(2x), 0, 4pi) # mix of simple, non-simple zeros -f(x) = (x-0.5) * (x-0.5001) * (x-1) # nearby zeros -find_zeros(f, 0, 2) -f(x) = (x-0.5) * (x-0.5001) * (x-4) * (x-4.001) * (x-4.2) -find_zeros(f, 0, 10) -f(x) = (x-0.5)^2 * (x-0.5001)^3 * (x-4) * (x-4.001) * (x-4.2)^2 # hard to identify -find_zeros(f, 0, 10, no_pts=21) # too hard for default +```jldoctest find_zeros +julia> using Roots + +julia> find_zeros(x -> exp(x) - x^4, -5, 20) # a few well-spaced zeros +3-element Array{Float64,1}: + -0.8155534188089606 + 1.4296118247255556 + 8.613169456441398 + +julia> find_zeros(x -> sin(x^2) + cos(x)^2, 0, 2pi) # many zeros +12-element Array{Float64,1}: + 1.78518032659534 + 2.391345462376604 + 3.2852368649448853 + 3.3625557095737544 + 4.016412952618305 + 4.325091924521049 + 4.68952781386834 + 5.00494459113514 + 5.35145266881871 + 5.552319796014526 + 5.974560835055425 + 6.039177477770888 + +julia> find_zeros(x -> cos(x) + cos(2x), 0, 4pi) # mix of simple, non-simple zeros +6-element Array{Float64,1}: + 1.0471975511965976 + 3.141592653589943 + 5.235987755982988 + 7.330382858376184 + 9.424777960769228 + 11.519173063162574 + +julia> f(x) = (x-0.5) * (x-0.5001) * (x-1) # nearby zeros +f (generic function with 1 method) + +julia> find_zeros(f, 0, 2) +3-element Array{Float64,1}: + 0.5 + 0.5001 + 1.0 + +julia> f(x) = (x-0.5) * (x-0.5001) * (x-4) * (x-4.001) * (x-4.2) +f (generic function with 1 method) + +julia> find_zeros(f, 0, 10) +3-element Array{Float64,1}: + 0.5 + 0.5001 + 4.2 + +julia> f(x) = (x-0.5)^2 * (x-0.5001)^3 * (x-4) * (x-4.001) * (x-4.2)^2 # hard to identify +f (generic function with 1 method) + +julia> find_zeros(f, 0, 10, no_pts=21) # too hard for default +5-element Array{Float64,1}: + 0.49999999999999994 + 0.5001 + 4.0 + 4.001 + 4.200000000000001 ``` -Notes: +!!! note + There are two cases where the number of zeros may be underreported: + * if the initial interval, [a,b], is too wide + * if there are zeros that are very nearby -There are two typical cases where the number of zeros may be -underreported: - -* if the initial interval, [a,b], is too wide - -* if there are nearby zeros +---- The basic algorithm checks for zeros among the endpoints, and then -divides the interval (a,b) into `no_pts-1` subintervals and then +divides the interval `(a,b)` into `no_pts-1` subintervals and then proceeds to look for zeros through bisection or a derivative-free method. As checking for a bracketing interval is relatively cheap and bisection is guaranteed to converge, each interval has `k` pairs of intermediate points checked for a bracket. -If any zeros are found, the algorithm uses these to partition (a,b) +If any zeros are found, the algorithm uses these to partition `(a,b)` into subintervals. Each subinterval is shrunk so that the endpoints are not zeros and the process is repeated on the subinterval. If the initial interval is too large, then the naive scanning for zeros may diff --git a/src/fzero.jl b/src/fzero.jl index 32f16274..7002f870 100644 --- a/src/fzero.jl +++ b/src/fzero.jl @@ -24,7 +24,7 @@ Find zero of a function using one of several iterative algorithms. use for `find_zero`. The `Order0` default may be specified directly by `order=0`, `order=:0`, or `order="0"`; `Order1()` by `order=1`, `order=:1`, `order="1"`, or `order=:secant`; `Order1B()` by - `order="1B", etc. + `order="1B"`, etc. * `M`: a specific method, as would be passed to `find_zero`, bypassing the use of the `order` keyword diff --git a/src/newton.jl b/src/newton.jl index 8701d90a..eb36d35e 100644 --- a/src/newton.jl +++ b/src/newton.jl @@ -15,12 +15,13 @@ ## Newton abstract type AbstractNewtonLikeMethod <: AbstractUnivariateZeroMethod end +struct Newton <: AbstractNewtonLikeMethod end """ Roots.Newton() -Implements Newton's [method](http://tinyurl.com/b4d7vls): `x_n1 = xn - -f(xn)/f'(xn)`. This is a quadratically converging method requiring +Implements Newton's [method](http://tinyurl.com/b4d7vls): +`xᵢ₊₁ = xᵢ - f(xᵢ)/f'(xᵢ)`. This is a quadratically convergent method requiring one derivative. Two function calls per step. Example @@ -37,10 +38,11 @@ find_zero(x -> (sin(x), sin(x)/cos(x)), 3.0, Roots.Newton()) This can be advantageous if the derivative is easily computed from the value of f, but otherwise would be expensive to compute. -The error, `en = xn - alpha`, can be expressed as `e1 = f[x0,x0,alpha]/(2f[x0,x0])e0^2` (Sidi). +The error, `eᵢ = xᵢ - α`, can be expressed as `eᵢ₊₁ = f[xᵢ,xᵢ,α]/(2f[xᵢ,xᵢ])eᵢ²` (Sidi, Unified treatment of regula falsi, Newton-Raphson, secant, and Steffensen methods for nonlinear equations). """ -struct Newton <: AbstractNewtonLikeMethod end +Newton + function init_state(method::AbstractNewtonLikeMethod, fs, x) @@ -128,7 +130,7 @@ abstract type AbstractHalleyLikeMethod <: AbstractUnivariateZeroMethod end Roots.Halley() Implements Halley's [method](http://tinyurl.com/yd83eytb), -`x_n1 = xn - f/f' * (1 - f/f' * f''/f' * 1/2)^(-1) +`xᵢ₊₁ = xᵢ - (f/f')(xᵢ) * (1 - (f/f')(xᵢ) * (f''/f')(xᵢ) * 1/2)^(-1)` This method is cubically converging, but requires more function calls per step (3) than other methods. @@ -147,8 +149,8 @@ find_zero(x -> (sin(x), sin(x)/cos(x), -cos(x)/sin(x)), 3.0, Roots.Halley()) This can be advantageous if the derivatives are easily computed from the value of f, but otherwise would be expensive to compute. -The error, `e_n = x_n - alpha`, satisfies -`e1 ≈ -(2f'⋅f''' -3⋅(f'')^2)/(12⋅(f'')^2) ⋅ e0^3` (all evaluated at `alpha`). +The error, `eᵢ = xᵢ - α`, satisfies +`eᵢ₊₁ ≈ -(2f'⋅f''' -3⋅(f'')²)/(12⋅(f'')²) ⋅ eᵢ³` (all evaluated at `α`). """ struct Halley <: AbstractHalleyLikeMethod @@ -234,14 +236,14 @@ halley(f, fp, fpp, x0; kwargs...) = find_zero((f, fp, fpp), x0, Halley(); kwargs Roots.Schroder() -Schröder's method, like Halley's method, utilizes f, f', and -f''. Unlike Halley it is quadratically converging, but this is +Schröder's method, like Halley's method, utilizes `f`, `f'`, and +`f''`. Unlike Halley it is quadratically converging, but this is independent of the multiplicity of the zero (cf. Schröder, E. "Über unendlich viele Algorithmen zur Auflösung der Gleichungen." Math. Ann. 2, 317-365, 1870; -http://mathworld.wolfram.com/SchroedersMethod.html). (Schröder's +[mathworld](http://mathworld.wolfram.com/SchroedersMethod.html)). Schröder's method applies Newton's method to `f/f'`, a function with all -simple zeros.) +simple zeros. Example @@ -257,16 +259,16 @@ find_zero((f, fp, fpp), 1.0, Roots.Schroder()) # 3 steps (Whereas, when `m=1`, Halley is 2 steps to Schröder's 3.) If function evaluations are expensive one can pass in a function which -returns (f, f/f',f'/f'') as follows +returns `(f, f/f',f'/f'')` as follows ``` find_zero(x -> (sin(x), sin(x)/cos(x), -cos(x)/sin(x)), 3.0, Roots.Schroder()) ``` This can be advantageous if the derivatives are easily computed from -the value of f, but otherwise would be expensive to compute. +the value of `f`, but otherwise would be expensive to compute. -The error, `e_n = x_n - alpha`, is the same as `Newton` with `f` replaced by `f/f'`. +The error, `eᵢ = xᵢ - α`, is the same as `Newton` with `f` replaced by `f/f'`. """ struct Schroder <: AbstractHalleyLikeMethod diff --git a/test/test_simple.jl b/test/test_simple.jl index 7bf5ead4..257b3aa5 100644 --- a/test/test_simple.jl +++ b/test/test_simple.jl @@ -35,7 +35,6 @@ using Test @test Roots.muller(cos, 1.0) ≈ π/2 expoly(z) = log(-z)*asin(z)/tanh(z) - @test Roots.muller(expoly, 0.2+0.5im) ≈ im*π/2 @test Roots.muller(expoly, -0.7-0.5im) ≈ -1.0 # dfree