{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Implemented based on Chandrupatla's original paper " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Let:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "a, b = init" }, { "__type": "Text", "__tag": 4046, "value": " be the left and right endpoints of the initial bracket," } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "xl" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "xr" }, { "__type": "Text", "__tag": 4046, "value": " be the left and right endpoints of the final bracket," } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "xmin = xl if abs(f(xl)) <= abs(f(xr)) else xr" }, { "__type": "Text", "__tag": 4046, "value": " be the final bracket endpoint with the smaller function value, and" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "fmin0 = min(f(a), f(b))" }, { "__type": "Text", "__tag": 4046, "value": " be the minimum of the two values of the function evaluated at the initial bracket endpoints." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Then the algorithm is considered to have converged when" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "abs(xr - xl) < xatol + abs(xmin) * xrtol" }, { "__type": "Text", "__tag": 4046, "value": " or" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "fun(xmin) <= fatol + abs(fmin0) * frtol" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This is equivalent to the termination condition described in " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": " with " }, { "__type": "InlineCode", "__tag": 4051, "value": "xrtol = 4e-10" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "xatol = 1e-5" }, { "__type": "Text", "__tag": 4046, "value": ", and " }, { "__type": "InlineCode", "__tag": 4051, "value": "fatol = frtol = 0" }, { "__type": "Text", "__tag": 4046, "value": ". However, the default values of the " }, { "__type": "ParamRef", "__tag": 4071, "name": "tolerances" }, { "__type": "Text", "__tag": 4046, "value": " dictionary are " }, { "__type": "InlineCode", "__tag": 4051, "value": "xatol = 4*tiny" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "xrtol = 4*eps" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "frtol = 0" }, { "__type": "Text", "__tag": 4046, "value": ", and " }, { "__type": "InlineCode", "__tag": 4051, "value": "fatol = tiny" }, { "__type": "Text", "__tag": 4046, "value": ", where " }, { "__type": "InlineCode", "__tag": 4051, "value": "eps" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "tiny" }, { "__type": "Text", "__tag": 4046, "value": " are the precision and smallest normal number of the result " }, { "__type": "InlineCode", "__tag": 4051, "value": "dtype" }, { "__type": "Text", "__tag": 4046, "value": " of function inputs and outputs." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Array API Standard Support" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "find_root", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.optimize._elementwise:find_root" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " has experimental support for Python Array API Standard compatible backends in addition to NumPy. Please consider testing these features by setting an environment variable " }, { "__type": "InlineCode", "__tag": 4051, "value": "SCIPY_ARRAY_API=1" }, { "__type": "Text", "__tag": 4046, "value": " and providing CuPy, PyTorch, JAX, or Dask arrays as array arguments. The following combinations of backend and device (or other capability) are supported." } ] }, { "__type": "Code", "__tag": 4050, "value": "==================== ==================== ====================\nLibrary CPU GPU\n==================== ==================== ====================\nNumPy ✅ n/a \nCuPy n/a ✅ \nPyTorch ✅ ✅ \nJAX ⛔ ⛔ \nDask ⛔ n/a \n==================== ==================== ====================", "execution_status": null, "out": "" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "See " }, { "__type": "CrossRef", "__tag": 4002, "value": "dev-arrayapi", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "dev:api-dev:array_api" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": " for more information." } ] } ], "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": "res", "annotation": "_RichResult", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An object similar to an instance of " }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.optimize.OptimizeResult", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "?", "kind": "module", "path": "scipy.optimize._optimize:OptimizeResult" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " with the following attributes. The descriptions are written as though the values will be scalars; however, if " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " returns an array, the outputs will be arrays of the same shape." } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "success" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "True" }, { "__type": "Text", "__tag": 4046, "value": " where the algorithm terminated successfully (status " }, { "__type": "InlineCode", "__tag": 4051, "value": "0" }, { "__type": "Text", "__tag": 4046, "value": "); " }, { "__type": "InlineCode", "__tag": 4051, "value": "False" }, { "__type": "Text", "__tag": 4046, "value": " otherwise." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "status" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An integer representing the exit status of the algorithm." } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "0" }, { "__type": "Text", "__tag": 4046, "value": "The algorithm converged to the specified tolerances." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "-1" }, { "__type": "Text", "__tag": 4046, "value": "The initial bracket was invalid." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "-2" }, { "__type": "Text", "__tag": 4046, "value": "The maximum number of iterations was reached." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "-3" }, { "__type": "Text", "__tag": 4046, "value": "A non-finite value was encountered." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "-4" }, { "__type": "Text", "__tag": 4046, "value": "Iteration was terminated by " }, { "__type": "ParamRef", "__tag": 4071, "name": "callback" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "1" }, { "__type": "Text", "__tag": 4046, "value": "The algorithm is proceeding normally (in " }, { "__type": "ParamRef", "__tag": 4071, "name": "callback" }, { "__type": "Text", "__tag": 4046, "value": " only)." } ] } ] } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "x" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The root of the function, if the algorithm terminated successfully." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "f_x" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The value of " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " evaluated at " }, { "__type": "InlineRole", "__tag": 4003, "value": "x", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "nfev" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The number of abscissae at which " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " was evaluated to find the root. This is distinct from the number of times " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " is " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "called" } ] }, { "__type": "Text", "__tag": 4046, "value": " because the the function may evaluated at multiple points in a single call." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "nit" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The number of iterations of the algorithm that were performed." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "bracket" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The lower and upper endpoints of the final bracket." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "f_bracket" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The value of " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " evaluated at the lower and upper endpoints of the bracket." } ] } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Find the root of a monotonic, real-valued function of a real variable." } ] } ], "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": "The function whose root is desired. The signature must be " } ] }, { "__type": "Code", "__tag": 4050, "value": "f(x: array, *args) -> array", "execution_status": null, "out": "" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "where each element of " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": " is a finite real and " }, { "__type": "InlineCode", "__tag": 4051, "value": "args" }, { "__type": "Text", "__tag": 4046, "value": " is a tuple, which may contain an arbitrary number of arrays that are broadcastable with " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " must be an elementwise function: each element " }, { "__type": "InlineCode", "__tag": 4051, "value": "f(x)[i]" }, { "__type": "Text", "__tag": 4046, "value": " must equal " }, { "__type": "InlineCode", "__tag": 4051, "value": "f(x[i])" }, { "__type": "Text", "__tag": 4046, "value": " for all indices " }, { "__type": "InlineCode", "__tag": 4051, "value": "i" }, { "__type": "Text", "__tag": 4046, "value": ". It must not mutate the array " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": " or the arrays in " }, { "__type": "InlineCode", "__tag": 4051, "value": "args" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "find_root", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.optimize._elementwise:find_root" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " seeks an array " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": " such that " }, { "__type": "InlineCode", "__tag": 4051, "value": "f(x)" }, { "__type": "Text", "__tag": 4046, "value": " is an array of zeros." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "init", "annotation": "2-tuple of float array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The lower and upper endpoints of a bracket surrounding the desired root. A bracket is valid if arrays " }, { "__type": "InlineCode", "__tag": 4051, "value": "xl, xr = init" }, { "__type": "Text", "__tag": 4046, "value": " satisfy " }, { "__type": "InlineCode", "__tag": 4051, "value": "xl < xr" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "sign(f(xl)) == -sign(f(xr))" }, { "__type": "Text", "__tag": 4046, "value": " elementwise. Arrays be broadcastable with one another and " }, { "__type": "ParamRef", "__tag": 4071, "name": "args" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "args", "annotation": "tuple of array_like, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Additional positional array arguments to be passed to " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": ". Arrays must be broadcastable with one another and the arrays of " }, { "__type": "ParamRef", "__tag": 4071, "name": "init" }, { "__type": "Text", "__tag": 4046, "value": ". If the callable for which the root is desired requires arguments that are not broadcastable with " }, { "__type": "InlineRole", "__tag": 4003, "value": "x", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", wrap that callable with " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " such that " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " accepts only " }, { "__type": "InlineRole", "__tag": 4003, "value": "x", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " and broadcastable " }, { "__type": "InlineCode", "__tag": 4051, "value": "*args" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "kwargs", "annotation": "dict of str:array_like, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Additional keyword arguments to be passed to " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": ". See " }, { "__type": "ParamRef", "__tag": 4071, "name": "args" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "tolerances", "annotation": "dictionary of floats, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Absolute and relative tolerances on the root and function value. Valid keys of the dictionary are:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "xatol" }, { "__type": "Text", "__tag": 4046, "value": " - absolute tolerance on the root" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "xrtol" }, { "__type": "Text", "__tag": 4046, "value": " - relative tolerance on the root" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "fatol" }, { "__type": "Text", "__tag": 4046, "value": " - absolute tolerance on the function value" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "frtol" }, { "__type": "Text", "__tag": 4046, "value": " - relative tolerance on the function value" } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "See Notes for default values and explicit termination conditions." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "maxiter", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The maximum number of iterations of the algorithm to perform. The default is the maximum possible number of bisections within the (normal) floating point numbers of the relevant dtype." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "callback", "annotation": "callable, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An optional user-supplied function to be called before the first iteration and after each iteration. Called as " }, { "__type": "InlineCode", "__tag": 4051, "value": "callback(res)" }, { "__type": "Text", "__tag": 4046, "value": ", where " }, { "__type": "InlineCode", "__tag": 4051, "value": "res" }, { "__type": "Text", "__tag": 4046, "value": " is a " }, { "__type": "InlineCode", "__tag": 4051, "value": "_RichResult" }, { "__type": "Text", "__tag": 4046, "value": " similar to that returned by " }, { "__type": "CrossRef", "__tag": 4002, "value": "find_root", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.optimize._elementwise:find_root" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " (but containing the current iterate's values of all variables). If " }, { "__type": "ParamRef", "__tag": 4071, "name": "callback" }, { "__type": "Text", "__tag": 4046, "value": " raises a " }, { "__type": "InlineCode", "__tag": 4051, "value": "StopIteration" }, { "__type": "Text", "__tag": 4046, "value": ", the algorithm will terminate immediately and " }, { "__type": "CrossRef", "__tag": 4002, "value": "find_root", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.optimize._elementwise:find_root" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " will return a result. " }, { "__type": "ParamRef", "__tag": 4071, "name": "callback" }, { "__type": "Text", "__tag": 4046, "value": " must not mutate " }, { "__type": "CrossRef", "__tag": 4002, "value": "res", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "res" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": " or its attributes." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For each element of the output of " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "CrossRef", "__tag": 4002, "value": "find_root", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.optimize._elementwise:find_root" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " seeks the scalar root that makes the element 0. This function currently uses Chandrupatla's bracketing algorithm " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": " and therefore requires argument " }, { "__type": "ParamRef", "__tag": 4071, "name": "init" }, { "__type": "Text", "__tag": 4046, "value": " to provide a bracket around the root: the function values at the two endpoints must have opposite signs." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Provided a valid bracket, " }, { "__type": "CrossRef", "__tag": 4002, "value": "find_root", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.optimize._elementwise:find_root" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " is guaranteed to converge to a solution that satisfies the provided " }, { "__type": "ParamRef", "__tag": 4071, "name": "tolerances" }, { "__type": "Text", "__tag": 4046, "value": " if the function is continuous within the bracket." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function works elementwise when " }, { "__type": "ParamRef", "__tag": 4071, "name": "init" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "ParamRef", "__tag": 4071, "name": "args" }, { "__type": "Text", "__tag": 4046, "value": " contain (broadcastable) arrays." } ] } ], "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/_elementwise.py", "item_line": 7, "item_type": "function", "aliases": [ "scipy.optimize._elementwise.find_root" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "Suppose we wish to find the root of the following function.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "def f(x, c=5):\n return x**3 - 2*x - c\n", "execution_status": "success", "out": "" }, { "__type": "Text", "__tag": 4046, "value": "\nFirst, we must find a valid bracket. The function is not monotonic,\nbut `bracket_root` may be able to provide a bracket.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "from scipy.optimize import elementwise\nres_bracket = elementwise.bracket_root(f, 0)\n", "execution_status": "success", "out": "" }, { "__type": "Code", "__tag": 4050, "value": "res_bracket.success\nres_bracket.bracket\n", "execution_status": "failure", "out": "(np.float64(2.0), np.float64(4.0))\n" }, { "__type": "Text", "__tag": 4046, "value": "\nIndeed, the values of the function at the bracket endpoints have\nopposite signs.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "res_bracket.f_bracket\n", "execution_status": "failure", "out": "(np.float64(-1.0), np.float64(51.0))\n" }, { "__type": "Text", "__tag": 4046, "value": "\nOnce we have a valid bracket, `find_root` can be used to provide\na precise root.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "res_root = elementwise.find_root(f, res_bracket.bracket)\n", "execution_status": "success", "out": "" }, { "__type": "Code", "__tag": 4050, "value": "res_root.x\n", "execution_status": "failure", "out": "np.float64(2.0945514815423265)\n" }, { "__type": "Text", "__tag": 4046, "value": "\nThe final bracket is only a few ULPs wide, so the error between\nthis value and the true root cannot be much smaller within values\nthat are representable in double precision arithmetic.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nxl, xr = res_root.bracket\n", "execution_status": "success", "out": "" }, { "__type": "Code", "__tag": 4050, "value": "(xr - xl) / np.spacing(xl)\nres_root.f_bracket\n", "execution_status": "failure", "out": "(np.float64(-8.881784197001252e-16), np.float64(9.769962616701378e-15))\n" }, { "__type": "Text", "__tag": 4046, "value": "\n`bracket_root` and `find_root` accept arrays for most arguments.\nFor instance, to find the root for a few values of the parameter ``c``\nat once:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "c = np.asarray([3, 4, 5])\nres_bracket = elementwise.bracket_root(f, 0, args=(c,))\nres_bracket.bracket\nres_root = elementwise.find_root(f, res_bracket.bracket, args=(c,))\n", "execution_status": "success", "out": "" }, { "__type": "Code", "__tag": 4050, "value": "res_root.x\n", "execution_status": "failure", "out": "array([1.89329, 2. , 2.09455])\n" } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "bracket_root", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.optimize._elementwise:bracket_root" }, "kind": "module" }, "descriptions": [], "type": "func" } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "f", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_ONLY", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "init", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_ONLY", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "args", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "()" }, { "__type": "SigParam", "__tag": 4030, "name": "kwargs", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "tolerances", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "maxiter", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "callback", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "find_root" }, "references": [ ".. [1] Chandrupatla, Tirupathi R.", " \"A new hybrid quadratic/bisection algorithm for finding the zero of a", " nonlinear function without using derivatives\".", " Advances in Engineering Software, 28(3), 145-149.", " :doi:`10.1016/s0965-9978(96)00051-8`." ], "qa": "scipy.optimize._elementwise:find_root", "arbitrary": [], "local_refs": [ "args", "callback", "f", "init", "kwargs", "maxiter", "res", "tolerances" ] }