{ "info": { "author": "Panagiotis Mavrogiorgos", "author_email": "gmail pmav99", "bugtrack_url": null, "classifiers": [ "Development Status :: 4 - Beta", "Intended Audience :: Developers", "License :: OSI Approved :: BSD License", "Operating System :: OS Independent", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.2", "Programming Language :: Python :: 3.3", "Programming Language :: Python :: Implementation :: CPython", "Programming Language :: Python :: Implementation :: PyPy", "Topic :: Scientific/Engineering", "Topic :: Scientific/Engineering :: Mathematics", "Topic :: Software Development :: Libraries", "Topic :: Software Development :: Libraries :: Python Modules" ], "description": "pyroots\n=======\n\nAbstract\n--------\n\nA Python library implementing various root finding methods for single-variable\nfunctions.\n\nCurrently the following methods have been implemented::\n\n* The `bisect `_ method.\n* The `ridder `_ method.\n* The `brent `_ method.\n\nWith regard to ``Brent``'s method, there are two implementations, the first one\nuses inverse quadratic extrapolation (``Brentq``) while the other ones uses\nhyperbolic extrapolation (``Brenth``).\n\nIf you don't know which method to use, you should probably use ``Brentq``. That\nbeing said, ``Bisect`` method is safe and slow.\n\nExample\n-------\n\n::\n\n # define the function whose root you are searching\n def f(x, a):\n return x ** 2 - a + 1\n\n # Create the Solver object (instead of Brentq you could also import Brenth/Ridder/Bisect)\n from pyroots import Brentq\n brent = Brentq(epsilon=1e-5)\n\n # solve the function in `[-3, 0]` while `a` is equal to 2\n result = brent(f, -3, 0, a=2)\n print(result)\n\nwill output::\n\n converged : True\n message : Solution converged.\n iteration : 6\n func calls : 9\n x0 : -1.0000000748530762\n xtol : 0.0000000000000002\n f(x0) : 0.0000001497061579\n epsilon : 0.0000100000000000\n\nRationale\n---------\n\nThe functionality of ``pyroots`` is already implemented in ``scipy``, so the\nnatural question is why rediscover the wheel?\n\nWell, the main reason is that ``scipy`` is a huge dependency. ``Pyroots`` on\nthe other hand is just a single package that is easily installed and that you\ncan easily bundle with ``py2exe`` or similar projects. It doesn't even need to\nget installed, just throw the ``pyroots`` folder in your project and you are\nready to go.\n\nApart from that, the API used by ``scipy``'s functions is not very\nuser-friendly. For example you can't use keyword arguments for your functions.\nMoreover, in ``scipy`` there is no reliable way to define how many digits of\naccuracy you want in the obtained root. For example, you may ask for 6 digits,\nbut scipy may calculate up to 14 (or 12 or whatever) digits. The main\nimplication of this \"glitch\" is that scipy's method may evaluate the function\nmore times than those really needed. If the function calculates something\ntrivial like the functions in the following examples, then these extra function\ncalls are no big deal, but if your functions take significant time to evaluate\n,e.g. more than seconds, then this can quickly become annoying, or even, simply\nunacceptable, e.g. the function takes some minutes to return a value.\n\nInstallation\n------------\n\nwith pip::\n\n pip install pyroots\n\nor from source::\n\n python setup.py install\n\nUsage\n-----\n\nAll the solvers share the same API, so you can easily switch between the\nvarious methods.\n\nFunction\n++++++++\n\nThe function whose root you are searching must take at least a single argument\nand return a single number. This first argument is also the dependent variable\nand, apart from that, the function can also take any number of\npositional/keyword arguments. For example the following functions are totally\nvalid ones::\n\n def f(x, a):\n return x ** 2 - a + 1\n\n def g(x, a, b, c=3):\n return x ** 2 + a ** b - c\n\nSolver Objects\n--------------\n\nThe first thing you have to do is to create a ``Solver`` object for the method\nyou want to use::\n\n from pyroots import Brentq\n\n brent = Brentq()\n\nWhen you create the ``Solver`` object, you can specify several parameters\nthat will affect the convergence. The most important are:\n\n* `epsilon` which specifies the number of digits that will be taken under\n consideration when checking for convergence. It defaults to `1e-6`.\n* `raise_on_fail` which will raise an exception if convergence failed. It\n defaults to `True`.\n\nUsing the above function definitions, in order to find the root of ``f`` you\nmust first define an interval that contains the root. Let's say that this\ninterval is defined as ``[xa, xb]``. In this case you will call the solver\nlike this::\n\n def f(x, a):\n return x ** 2 - a + 1\n\n solver = Brentq()\n result = solver(f, xa, xb, a=3)\n\nResult Objects\n--------------\n\nAll the methods return a ``Result`` object that has the following attributes::\n\n result.x0 # the root\n result.fx0 # the value of ``f(x0)`\n result.convergence # True/False\n result.iterations # the number of iterations\n result.func_calls # the number of function evaluations.\n result.msg # a descriptive message regarding the convergence (or the failure of convergence)\n\nIf, for some reason, convergence cannot be achieved, then a ``ConvergenceError``\nis raised. If you don't want that to happen, then you have to pass ``False`` as\nthe value of ``raise_on_fail`` argument::\n\n def f(x):\n return x ** 2 - 1\n\n result = brent(f, xa=-10, xb=-5, raise_on_fail=False):\n print(result)\n\nAPI\n---\n\nEach solver factory has the following signature::\n\n SolverFactory(epsilon=1e-6, xtol=EPS, max_iter=500, raise_on_fail=True, debug_precision=10)\n\nwhere:\n\n* ``epsilon`` is the required precision of the solution, i.e. a solution is\n achieved when ``|f(x0)|`` is smaller than ``epsilon``.\n* ``max_iter`` is the maximum allowed number of iterations.\n* ``raise_on_fail`` is a boolean flag indicating whether or not an exception\n should be raised if convergence fails. It defaults to True\n\nEach solver object has the following signature::\n\n solver_object(f, xa, xb, *args, **kwargs)\n\nwhere:\n\n* ``f`` is the function whose root we are searching.\n* ``xa`` is the lower bracket of the interval of the solution we search.\n* ``xb`` is the upper bracket of the interval of the solution we search.\n* ``*args`` are passed as positional arguments when ``f`` is evaluated.\n* ``**kwargs`` are passed as keyword arguments when ``f`` is evaluated.\n\nDocumentation\n-------------\n\nFor the time being documentation is not yet ready, but the examples in the\nREADME should be enough to get your feet wet.\n\nThe source code repository of pyroots can be found at: https://github.com/pmav99/pyroots\n\nFeedback and contributions are greatly appreciated.\n\npmav99 ", "description_content_type": null, "docs_url": null, "download_url": "http://github.com/pmav99/pyroots/archive/master.zip", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "http://github.com/pmav99/pyroots", "keywords": "numeric analysis,brent,bisect,ridder", "license": "", "maintainer": "", "maintainer_email": "", "name": "pyroots", "package_url": "https://pypi.org/project/pyroots/", "platform": "OS Independent", "project_url": "https://pypi.org/project/pyroots/", "project_urls": { "Download": "http://github.com/pmav99/pyroots/archive/master.zip", "Homepage": "http://github.com/pmav99/pyroots" }, "release_url": "https://pypi.org/project/pyroots/0.3.2/", "requires_dist": null, "requires_python": "", "summary": "A python-only implementation of single-variable root finding methods", "version": "0.3.2" }, "last_serial": 2574290, "releases": { "0.1.0": [ { "comment_text": "", "digests": { "md5": "460a1895109836b532cc5eebc05fe1ac", "sha256": "d78ceec0f1b202dfc4b3cd8e2564c4dfb4bf156f3d1073a535d3633686fd8a11" }, "downloads": -1, "filename": "pyroots-0.1.0.tar.gz", "has_sig": false, "md5_digest": "460a1895109836b532cc5eebc05fe1ac", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 9307, "upload_time": "2013-03-20T15:23:51", "url": "https://files.pythonhosted.org/packages/31/fa/80a4a8b25e3e440fcaa7e7ae7863df7162570f0399949e8b0f612d3eca59/pyroots-0.1.0.tar.gz" } ], "0.3.0": [], "0.3.2": [ { "comment_text": "", "digests": { "md5": "1839472428cafa09dda2ea50d68dad43", "sha256": "091216cbfbb743fa48af83fdd74d8d9aa6a28a5e5abe0fdb2713d49e2d7624f2" }, "downloads": -1, "filename": "pyroots-0.3.2-py2.py3-none-any.whl", "has_sig": false, "md5_digest": "1839472428cafa09dda2ea50d68dad43", "packagetype": "bdist_wheel", "python_version": "py2.py3", "requires_python": null, "size": 21342, "upload_time": "2017-01-14T17:29:22", "url": "https://files.pythonhosted.org/packages/bb/50/f0f3225c141d48df56c09bada9f2c9e26382b7dd663ea6e3f24154504ada/pyroots-0.3.2-py2.py3-none-any.whl" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "1839472428cafa09dda2ea50d68dad43", "sha256": "091216cbfbb743fa48af83fdd74d8d9aa6a28a5e5abe0fdb2713d49e2d7624f2" }, "downloads": -1, "filename": "pyroots-0.3.2-py2.py3-none-any.whl", "has_sig": false, "md5_digest": "1839472428cafa09dda2ea50d68dad43", "packagetype": "bdist_wheel", "python_version": "py2.py3", "requires_python": null, "size": 21342, "upload_time": "2017-01-14T17:29:22", "url": "https://files.pythonhosted.org/packages/bb/50/f0f3225c141d48df56c09bada9f2c9e26382b7dd663ea6e3f24154504ada/pyroots-0.3.2-py2.py3-none-any.whl" } ] }