{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The implementation was inspired by jacobi " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": ", numdifftools " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": ", and DERIVEST " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "3" }, { "__type": "Text", "__tag": 4046, "value": ", but the implementation follows the theory of Taylor series more straightforwardly (and arguably naively so). In the first iteration, the derivative is estimated using a finite difference formula of order " }, { "__type": "ParamRef", "__tag": 4071, "name": "order" }, { "__type": "Text", "__tag": 4046, "value": " with maximum step size " }, { "__type": "ParamRef", "__tag": 4071, "name": "initial_step" }, { "__type": "Text", "__tag": 4046, "value": ". Each subsequent iteration, the maximum step size is reduced by " }, { "__type": "ParamRef", "__tag": 4071, "name": "step_factor" }, { "__type": "Text", "__tag": 4046, "value": ", and the derivative is estimated again until a termination condition is reached. The error estimate is the magnitude of the difference between the current derivative approximation and that of the previous iteration." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The stencils of the finite difference formulae are designed such that abscissae are \"nested\": after " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " is evaluated at " }, { "__type": "InlineCode", "__tag": 4051, "value": "order + 1" }, { "__type": "Text", "__tag": 4046, "value": " points in the first iteration, " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " is evaluated at only two new points in each subsequent iteration; " }, { "__type": "InlineCode", "__tag": 4051, "value": "order - 1" }, { "__type": "Text", "__tag": 4046, "value": " previously evaluated function values required by the finite difference formula are reused, and two function values (evaluations at the points furthest from " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": ") are unused." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Step sizes are absolute. When the step size is small relative to the magnitude of " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": ", precision is lost; for example, if " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": " is " }, { "__type": "InlineCode", "__tag": 4051, "value": "1e20" }, { "__type": "Text", "__tag": 4046, "value": ", the default initial step size of " }, { "__type": "InlineCode", "__tag": 4051, "value": "0.5" }, { "__type": "Text", "__tag": 4046, "value": " cannot be resolved. Accordingly, consider using larger initial step sizes for large magnitudes of " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The default tolerances are challenging to satisfy at points where the true derivative is exactly zero. If the derivative may be exactly zero, consider specifying an absolute tolerance (e.g. " }, { "__type": "InlineCode", "__tag": 4051, "value": "atol=1e-12" }, { "__type": "Text", "__tag": 4046, "value": ") to improve convergence." } ] } ], "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 error estimate increased, so iteration was terminated." } ] } ] }, { "__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": "df" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The derivative of " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " at " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": ", if the algorithm terminated successfully." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "error" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An estimate of the error: the magnitude of the difference between the current estimate of the derivative and the estimate in the previous iteration." } ] } ] }, { "__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": "nfev" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The number of points at which " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " was evaluated." } ] } ] }, { "__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 value at which the derivative of " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " was evaluated (after broadcasting with " }, { "__type": "ParamRef", "__tag": 4071, "name": "args" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "ParamRef", "__tag": 4071, "name": "step_direction" }, { "__type": "Text", "__tag": 4046, "value": ")." } ] } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Evaluate the derivative of an elementwise, real scalar function numerically." } ] } ], "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 derivative is desired. The signature must be " } ] }, { "__type": "Code", "__tag": 4050, "value": "f(xi: ndarray, *argsi) -> ndarray", "execution_status": null, "out": "" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "where each element of " }, { "__type": "InlineCode", "__tag": 4051, "value": "xi" }, { "__type": "Text", "__tag": 4046, "value": " is a finite real number and " }, { "__type": "InlineCode", "__tag": 4051, "value": "argsi" }, { "__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": "xi" }, { "__type": "Text", "__tag": 4046, "value": ". " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " must be an elementwise function: each scalar element " }, { "__type": "InlineCode", "__tag": 4051, "value": "f(xi)[j]" }, { "__type": "Text", "__tag": 4046, "value": " must equal " }, { "__type": "InlineCode", "__tag": 4051, "value": "f(xi[j])" }, { "__type": "Text", "__tag": 4046, "value": " for valid indices " }, { "__type": "InlineCode", "__tag": 4051, "value": "j" }, { "__type": "Text", "__tag": 4046, "value": ". It must not mutate the array " }, { "__type": "InlineCode", "__tag": 4051, "value": "xi" }, { "__type": "Text", "__tag": 4046, "value": " or the arrays in " }, { "__type": "InlineCode", "__tag": 4051, "value": "argsi" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "x", "annotation": "float array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Abscissae at which to evaluate the derivative. Must be broadcastable with " }, { "__type": "ParamRef", "__tag": 4071, "name": "args" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "ParamRef", "__tag": 4071, "name": "step_direction" }, { "__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": "InlineRole", "__tag": 4003, "value": "init", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ". If the callable for which the root is desired requires arguments that are not broadcastable with " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__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": "ParamRef", "__tag": 4071, "name": "x" }, { "__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. 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": "atol" }, { "__type": "Text", "__tag": 4046, "value": " - absolute tolerance on the derivative" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "rtol" }, { "__type": "Text", "__tag": 4046, "value": " - relative tolerance on the derivative" } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Iteration will stop when " }, { "__type": "InlineCode", "__tag": 4051, "value": "res.error < atol + rtol * abs(res.df)" }, { "__type": "Text", "__tag": 4046, "value": ". The default " }, { "__type": "InlineRole", "__tag": 4003, "value": "atol", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " is the smallest normal number of the appropriate dtype, and the default " }, { "__type": "InlineRole", "__tag": 4003, "value": "rtol", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " is the square root of the precision of the appropriate dtype." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "maxiter", "annotation": "int, default: 10", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The maximum number of iterations of the algorithm to perform. See Notes." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "order", "annotation": "int, default: 8", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The (positive integer) order of the finite difference formula to be used. Odd integers will be rounded up to the next even integer." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "initial_step", "annotation": "float array_like, default: 0.5", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The (absolute) initial step size for the finite difference derivative approximation." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "step_factor", "annotation": "float, default: 2.0", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The factor by which the step size is " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "reduced" } ] }, { "__type": "Text", "__tag": 4046, "value": " in each iteration; i.e. the step size in iteration 1 is " }, { "__type": "InlineCode", "__tag": 4051, "value": "initial_step/step_factor" }, { "__type": "Text", "__tag": 4046, "value": ". If " }, { "__type": "InlineCode", "__tag": 4051, "value": "step_factor < 1" }, { "__type": "Text", "__tag": 4046, "value": ", subsequent steps will be greater than the initial step; this may be useful if steps smaller than some threshold are undesirable (e.g. due to subtractive cancellation error)." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "step_direction", "annotation": "int array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An array representing the direction of the finite difference steps (for use when " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": " lies near to the boundary of the domain of the function.) Must be broadcastable with " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": " and all " }, { "__type": "ParamRef", "__tag": 4071, "name": "args" }, { "__type": "Text", "__tag": 4046, "value": ". Where 0 (default), central differences are used; where negative (e.g. -1), steps are non-positive; and where positive (e.g. 1), all steps are non-negative." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "preserve_shape", "annotation": "bool, default: False", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In the following, \"arguments of " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": "\" refers to the array " }, { "__type": "InlineCode", "__tag": 4051, "value": "xi" }, { "__type": "Text", "__tag": 4046, "value": " and any arrays within " }, { "__type": "InlineCode", "__tag": 4051, "value": "argsi" }, { "__type": "Text", "__tag": 4046, "value": ". Let " }, { "__type": "InlineCode", "__tag": 4051, "value": "shape" }, { "__type": "Text", "__tag": 4046, "value": " be the broadcasted shape of " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": " and all elements of " }, { "__type": "ParamRef", "__tag": 4071, "name": "args" }, { "__type": "Text", "__tag": 4046, "value": " (which is conceptually distinct from " }, { "__type": "InlineCode", "__tag": 4051, "value": "xi` and ``argsi" }, { "__type": "Text", "__tag": 4046, "value": " passed into " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": ")." } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When " }, { "__type": "InlineCode", "__tag": 4051, "value": "preserve_shape=False" }, { "__type": "Text", "__tag": 4046, "value": " (default), " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " must accept arguments of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "any" } ] }, { "__type": "Text", "__tag": 4046, "value": " broadcastable shapes." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When " }, { "__type": "InlineCode", "__tag": 4051, "value": "preserve_shape=True" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " must accept arguments of shape " }, { "__type": "InlineCode", "__tag": 4051, "value": "shape + (n,)" }, { "__type": "Text", "__tag": 4046, "value": ", where " }, { "__type": "InlineCode", "__tag": 4051, "value": "n" }, { "__type": "Text", "__tag": 4046, "value": " is the number of abscissae at which the function is being evaluated." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In either case, for each scalar element " }, { "__type": "InlineCode", "__tag": 4051, "value": "xi[j]" }, { "__type": "Text", "__tag": 4046, "value": " within " }, { "__type": "InlineCode", "__tag": 4051, "value": "xi" }, { "__type": "Text", "__tag": 4046, "value": ", the array returned by " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " must include the scalar " }, { "__type": "InlineCode", "__tag": 4051, "value": "f(xi[j])" }, { "__type": "Text", "__tag": 4046, "value": " at the same index. Consequently, the shape of the output is always the shape of the input " }, { "__type": "InlineCode", "__tag": 4051, "value": "xi" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "See Examples." } ] } ] }, { "__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": "derivative", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.differentiate._differentiate:derivative" }, "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": "derivative", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.differentiate._differentiate:derivative" }, "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": "derivative", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.differentiate._differentiate:derivative" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " approximates the first derivative of " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " at the corresponding element of " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": " using finite difference differentiation." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function works elementwise when " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "ParamRef", "__tag": 4071, "name": "step_direction" }, { "__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": "build-install/usr/lib/python3.14/site-packages/scipy/differentiate/_differentiate.py", "item_line": 71, "item_type": "function", "aliases": [ "scipy.differentiate.derivative" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "Evaluate the derivative of ``np.exp`` at several points ``x``.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy.differentiate import derivative\nf = np.exp\ndf = np.exp # true derivative\nx = np.linspace(1, 2, 5)\nres = derivative(f, x)\n", "execution_status": "success", "out": "" }, { "__type": "Code", "__tag": 4050, "value": "res.df # approximation of the derivative\nres.error # estimate of the error\nabs(res.df - df(x)) # true error\n", "execution_status": "failure", "out": "array([2.26e-14, 3.38e-14, 6.13e-14, 9.68e-14, 1.22e-13])\n" }, { "__type": "Text", "__tag": 4046, "value": "\nShow the convergence of the approximation as the step size is reduced.\nEach iteration, the step size is reduced by `step_factor`, so for\nsufficiently small initial step, each iteration reduces the error by a\nfactor of ``1/step_factor**order`` until finite precision arithmetic\ninhibits further improvement.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import matplotlib.pyplot as plt\niter = list(range(1, 12)) # maximum iterations\nhfac = 2 # step size reduction per iteration\nhdir = [-1, 0, 1] # compare left-, central-, and right- steps\norder = 4 # order of differentiation formula\nx = 1\nref = df(x)\nerrors = [] # true error\nfor i in iter:\n res = derivative(f, x, maxiter=i, step_factor=hfac,\n step_direction=hdir, order=order,\n # prevent early termination\n tolerances=dict(atol=0, rtol=0))\n errors.append(abs(res.df - ref))\nerrors = np.array(errors)\n", "execution_status": "success", "out": "" }, { "__type": "Code", "__tag": 4050, "value": "plt.semilogy(iter, errors[:, 0], label='left differences')\nplt.semilogy(iter, errors[:, 1], label='central differences')\nplt.semilogy(iter, errors[:, 2], label='right differences')\nplt.xlabel('iteration')\nplt.ylabel('error')\nplt.legend()\n", "execution_status": "failure", "out": "\n" }, { "__type": "Code", "__tag": 4050, "value": "plt.show()\n", "execution_status": "success", "out": "" }, { "__type": "Figure", "__tag": 4024, "value": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "2.0.0.dev0+git20260907.41eeb59", "kind": "assets", "path": "fig-640f0ee2db612afb.png" } }, { "__type": "Code", "__tag": 4050, "value": "(errors[1, 1] / errors[0, 1], 1 / hfac**order)\n", "execution_status": "failure", "out": "(np.float64(0.062152231405411804), 0.0625)\n" }, { "__type": "Text", "__tag": 4046, "value": "\nThe implementation is vectorized over `x`, `step_direction`, and `args`.\nThe function is evaluated once before the first iteration to perform input\nvalidation and standardization, and once per iteration thereafter.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "def f(x, p):\n f.nit += 1\n return x**p\nf.nit = 0\ndef df(x, p):\n return p*x**(p-1)\nx = np.arange(1, 5)\np = np.arange(1, 6).reshape((-1, 1))\nhdir = np.arange(-1, 2).reshape((-1, 1, 1))\nres = derivative(f, x, args=(p,), step_direction=hdir, maxiter=1)\nnp.allclose(res.df, df(x, p))\nres.df.shape\nf.nit\n", "execution_status": "success", "out": "2\n" }, { "__type": "Text", "__tag": 4046, "value": "\nBy default, `preserve_shape` is False, and therefore the callable\n`f` may be called with arrays of any broadcastable shapes.\nFor example:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "shapes = []\ndef f(x, c):\n shape = np.broadcast_shapes(x.shape, c.shape)\n shapes.append(shape)\n return np.sin(c*x)\nc = [1, 5, 10, 20]\nres = derivative(f, 0, args=(c,))\nshapes\n", "execution_status": "success", "out": "[(4,), (4, 8), (4, 2), (3, 2), (2, 2), (1, 2)]\n" }, { "__type": "Text", "__tag": 4046, "value": "\nTo understand where these shapes are coming from - and to better\nunderstand how `derivative` computes accurate results - note that\nhigher values of ``c`` correspond with higher frequency sinusoids.\nThe higher frequency sinusoids make the function's derivative change\nfaster, so more function evaluations are required to achieve the target\naccuracy:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "res.nfev\n", "execution_status": "success", "out": "array([11, 13, 15, 17], dtype=int32)\n" }, { "__type": "Text", "__tag": 4046, "value": "\nThe initial ``shape``, ``(4,)``, corresponds with evaluating the\nfunction at a single abscissa and all four frequencies; this is used\nfor input validation and to determine the size and dtype of the arrays\nthat store results. The next shape corresponds with evaluating the\nfunction at an initial grid of abscissae and all four frequencies.\nSuccessive calls to the function evaluate the function at two more\nabscissae, increasing the effective order of the approximation by two.\nHowever, in later function evaluations, the function is evaluated at\nfewer frequencies because the corresponding derivative has already\nconverged to the required tolerance. This saves function evaluations to\nimprove performance, but it requires the function to accept arguments of\nany shape.\n\n\"Vector-valued\" functions are unlikely to satisfy this requirement.\nFor example, consider\n\n" }, { "__type": "Code", "__tag": 4050, "value": "def f(x):\n return [x, np.sin(3*x), x+np.sin(10*x), np.sin(20*x)*(x-1)**2]\n", "execution_status": "success", "out": "" }, { "__type": "Text", "__tag": 4046, "value": "\nThis integrand is not compatible with `derivative` as written; for instance,\nthe shape of the output will not be the same as the shape of ``x``. Such a\nfunction *could* be converted to a compatible form with the introduction of\nadditional parameters, but this would be inconvenient. In such cases,\na simpler solution would be to use `preserve_shape`.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "shapes = []\ndef f(x):\n shapes.append(x.shape)\n x0, x1, x2, x3 = x\n return [x0, np.sin(3*x1), x2+np.sin(10*x2), np.sin(20*x3)*(x3-1)**2]\nx = np.zeros(4)\nres = derivative(f, x, preserve_shape=True)\nshapes\n", "execution_status": "success", "out": "[(4, 1), (4, 8), (4, 2), (4, 2), (4, 2), (4, 2)]\n" }, { "__type": "Text", "__tag": 4046, "value": "\nHere, the shape of input ``x`` is ``(4,)``. With ``preserve_shape=True``, the\ncallable ``f`` is always called with argument ``x`` of shape ``(4, n)``,\nwhere ``n`` is any number of abscissae." } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "hessian", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.differentiate._differentiate:hessian" }, "kind": "module" }, "descriptions": [], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "jacobian", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.differentiate._differentiate:jacobian" }, "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_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "x", "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": "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": "10" }, { "__type": "SigParam", "__tag": 4030, "name": "order", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "8" }, { "__type": "SigParam", "__tag": 4030, "name": "initial_step", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "0.5" }, { "__type": "SigParam", "__tag": 4030, "name": "step_factor", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "2.0" }, { "__type": "SigParam", "__tag": 4030, "name": "step_direction", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "0" }, { "__type": "SigParam", "__tag": 4030, "name": "preserve_shape", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "False" }, { "__type": "SigParam", "__tag": 4030, "name": "callback", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "derivative" }, "references": [ ".. [1] Hans Dembinski (@HDembinski). jacobi.", " https://github.com/HDembinski/jacobi", ".. [2] Per A. Brodtkorb and John D'Errico. numdifftools.", " https://numdifftools.readthedocs.io/en/latest/", ".. [3] John D'Errico. DERIVEST: Adaptive Robust Numerical Differentiation.", " https://www.mathworks.com/matlabcentral/fileexchange/13490-adaptive-robust-numerical-differentiation", ".. [4] Numerical Differentition. Wikipedia.", " https://en.wikipedia.org/wiki/Numerical_differentiation" ], "qa": "scipy.differentiate._differentiate:derivative", "arbitrary": [], "local_refs": [ "args", "callback", "f", "initial_step", "kwargs", "maxiter", "order", "preserve_shape", "res", "step_direction", "step_factor", "tolerances", "x" ] }