{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This section describes the available solvers that can be selected by the 'method' parameter." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The default is to use the best method available for the situation presented. If a bracket is provided, it may use one of the bracketing methods. If a derivative and an initial value are specified, it may select one of the derivative-based methods. If no method is judged applicable, it will raise an Exception." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Arguments for each method are as follows (x=required, o=optional)." } ] }, { "__type": "Code", "__tag": 4050, "value": "+-----------------------------------------------+---+------+---------+----+----+--------+---------+------+------+---------+---------+\n| method | f | args | bracket | x0 | x1 | fprime | fprime2 | xtol | rtol | maxiter | options |\n+===============================================+===+======+=========+====+====+========+=========+======+======+=========+=========+\n| :ref:`bisect ` | x | o | x | | | | | o | o | o | o |\n+-----------------------------------------------+---+------+---------+----+----+--------+---------+------+------+---------+---------+\n| :ref:`brentq ` | x | o | x | | | | | o | o | o | o |\n+-----------------------------------------------+---+------+---------+----+----+--------+---------+------+------+---------+---------+\n| :ref:`brenth ` | x | o | x | | | | | o | o | o | o |\n+-----------------------------------------------+---+------+---------+----+----+--------+---------+------+------+---------+---------+\n| :ref:`ridder ` | x | o | x | | | | | o | o | o | o |\n+-----------------------------------------------+---+------+---------+----+----+--------+---------+------+------+---------+---------+\n| :ref:`toms748 ` | x | o | x | | | | | o | o | o | o |\n+-----------------------------------------------+---+------+---------+----+----+--------+---------+------+------+---------+---------+\n| :ref:`secant ` | x | o | | x | o | | | o | o | o | o |\n+-----------------------------------------------+---+------+---------+----+----+--------+---------+------+------+---------+---------+\n| :ref:`newton ` | x | o | | x | | o | | o | o | o | o |\n+-----------------------------------------------+---+------+---------+----+----+--------+---------+------+------+---------+---------+\n| :ref:`halley ` | x | o | | x | | x | x | o | o | o | o |\n+-----------------------------------------------+---+------+---------+----+----+--------+---------+------+------+---------+---------+", "execution_status": null } ], "title": [], "level": 0, "target": null }, "Warns": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Raises": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Yields": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Methods": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Returns": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "sol", "annotation": "RootResults", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The solution represented as a " }, { "__type": "InlineCode", "__tag": 4051, "value": "RootResults" }, { "__type": "Text", "__tag": 4046, "value": " object. Important attributes are: " }, { "__type": "InlineCode", "__tag": 4051, "value": "root" }, { "__type": "Text", "__tag": 4046, "value": " the solution , " }, { "__type": "InlineCode", "__tag": 4051, "value": "converged" }, { "__type": "Text", "__tag": 4046, "value": " a boolean flag indicating if the algorithm exited successfully and " }, { "__type": "InlineCode", "__tag": 4051, "value": "flag" }, { "__type": "Text", "__tag": 4046, "value": " which describes the cause of the termination. See " }, { "__type": "CrossRef", "__tag": 4002, "value": "RootResults", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.optimize._zeros_py:RootResults" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " for a description of other attributes." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Find a root of a scalar function." } ] } ], "title": [], "level": 0, "target": null }, "Receives": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Warnings": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Attributes": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Parameters": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "f", "annotation": "callable", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A function to find a root of." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Suppose the callable has signature " }, { "__type": "InlineCode", "__tag": 4051, "value": "f0(x, *my_args, **my_kwargs)" }, { "__type": "Text", "__tag": 4046, "value": ", where " }, { "__type": "InlineCode", "__tag": 4051, "value": "my_args" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "my_kwargs" }, { "__type": "Text", "__tag": 4046, "value": " are required positional and keyword arguments. Rather than passing " }, { "__type": "InlineCode", "__tag": 4051, "value": "f0" }, { "__type": "Text", "__tag": 4046, "value": " as the callable, wrap it to accept only " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": "; e.g., pass " }, { "__type": "InlineCode", "__tag": 4051, "value": "fun=lambda x: f0(x, *my_args, **my_kwargs)" }, { "__type": "Text", "__tag": 4046, "value": " as the callable, where " }, { "__type": "InlineCode", "__tag": 4051, "value": "my_args" }, { "__type": "Text", "__tag": 4046, "value": " (tuple) and " }, { "__type": "InlineCode", "__tag": 4051, "value": "my_kwargs" }, { "__type": "Text", "__tag": 4046, "value": " (dict) have been gathered before invoking this function." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "args", "annotation": "tuple, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Extra arguments passed to the objective function and its derivative(s)." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "method", "annotation": "str, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Type of solver. Should be one of" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'bisect' " }, { "__type": "InlineRole", "__tag": 4003, "value": "(see here) ", "domain": null, "role": "ref", "inventory": null } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'brentq' " }, { "__type": "InlineRole", "__tag": 4003, "value": "(see here) ", "domain": null, "role": "ref", "inventory": null } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'brenth' " }, { "__type": "InlineRole", "__tag": 4003, "value": "(see here) ", "domain": null, "role": "ref", "inventory": null } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'ridder' " }, { "__type": "InlineRole", "__tag": 4003, "value": "(see here) ", "domain": null, "role": "ref", "inventory": null } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'toms748' " }, { "__type": "InlineRole", "__tag": 4003, "value": "(see here) ", "domain": null, "role": "ref", "inventory": null } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'newton' " }, { "__type": "InlineRole", "__tag": 4003, "value": "(see here) ", "domain": null, "role": "ref", "inventory": null } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'secant' " }, { "__type": "InlineRole", "__tag": 4003, "value": "(see here) ", "domain": null, "role": "ref", "inventory": null } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'halley' " }, { "__type": "InlineRole", "__tag": 4003, "value": "(see here) ", "domain": null, "role": "ref", "inventory": null } ] } ] } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "bracket: A sequence of 2 floats, optional", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An interval bracketing a root. " }, { "__type": "InlineCode", "__tag": 4051, "value": "f(x, *args)" }, { "__type": "Text", "__tag": 4046, "value": " must have different signs at the two endpoints." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "x0", "annotation": "float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Initial guess." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "x1", "annotation": "float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A second guess." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "fprime", "annotation": "bool or callable, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "ParamRef", "__tag": 4071, "name": "fprime" }, { "__type": "Text", "__tag": 4046, "value": " is a boolean and is True, " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " is assumed to return the value of the objective function and of the derivative. " }, { "__type": "ParamRef", "__tag": 4071, "name": "fprime" }, { "__type": "Text", "__tag": 4046, "value": " can also be a callable returning the derivative of " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": ". In this case, it must accept the same arguments as " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "fprime2", "annotation": "bool or callable, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "ParamRef", "__tag": 4071, "name": "fprime2" }, { "__type": "Text", "__tag": 4046, "value": " is a boolean and is True, " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " is assumed to return the value of the objective function and of the first and second derivatives. " }, { "__type": "ParamRef", "__tag": 4071, "name": "fprime2" }, { "__type": "Text", "__tag": 4046, "value": " can also be a callable returning the second derivative of " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": ". In this case, it must accept the same arguments as " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "xtol", "annotation": "float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Tolerance (absolute) for termination." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "rtol", "annotation": "float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Tolerance (relative) for termination." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "maxiter", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Maximum number of iterations." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "options", "annotation": "dict, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A dictionary of solver options. E.g., " }, { "__type": "InlineCode", "__tag": 4051, "value": "k" }, { "__type": "Text", "__tag": 4046, "value": ", see " }, { "__type": "InlineRole", "__tag": 4003, "value": "show_options()", "domain": null, "role": "obj", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " for details." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Other Parameters": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null } }, "_ordered_sections": [ "Summary", "Extended Summary", "Parameters", "Attributes", "Methods", "Returns", "Yields", "Receives", "Other Parameters", "Raises", "Warns", "Warnings", "Notes" ], "item_file": "/scipy/optimize/_root_scalar.py", "item_line": 62, "item_type": "function", "aliases": [ "scipy.optimize.root_scalar" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "Find the root of a simple cubic\n\n" }, { "__type": "Code", "__tag": 4050, "value": "from scipy import optimize\ndef f(x):\n return (x**3 - 1) # only one real root at x = 1\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "def fprime(x):\n return 3*x**2\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe `brentq` method takes as input a bracket\n\n" }, { "__type": "Code", "__tag": 4050, "value": "sol = optimize.root_scalar(f, bracket=[0, 3], method='brentq')\nsol.root, sol.iterations, sol.function_calls\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe `newton` method takes as input a single point and uses the\nderivative(s).\n\n" }, { "__type": "Code", "__tag": 4050, "value": "sol = optimize.root_scalar(f, x0=0.2, fprime=fprime, method='newton')\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "sol.root, sol.iterations, sol.function_calls\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nThe function can provide the value and derivative(s) in a single call.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "def f_p_pp(x):\n return (x**3 - 1), 3*x**2, 6*x\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "sol = optimize.root_scalar(\n f_p_pp, x0=0.2, fprime=True, method='newton'\n)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "sol.root, sol.iterations, sol.function_calls\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "sol = optimize.root_scalar(\n f_p_pp, x0=0.2, fprime=True, fprime2=True, method='halley'\n)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "sol.root, sol.iterations, sol.function_calls\n", "execution_status": "failure" } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "root", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.optimize._root:root" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Find a root of a vector function." } ] } ], "type": null }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "show_options", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.optimize._optimize:show_options" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Additional options accepted by the solvers" } ] } ], "type": null } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "f", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "args", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "()" }, { "__type": "SigParam", "__tag": 4030, "name": "method", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "bracket", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "fprime", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "fprime2", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "x0", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "x1", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "xtol", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "rtol", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "maxiter", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "options", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "root_scalar" }, "references": null, "qa": "scipy.optimize._root_scalar:root_scalar", "arbitrary": [], "local_refs": [ "args", "bracket: A sequence of 2 floats", "f", "fprime", "fprime2", "maxiter", "method", "optional", "options", "rtol", "sol", "x0", "x1", "xtol" ] }