{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This class implements a memoization logic. There are methods " }, { "__type": "ParamRef", "__tag": 4071, "name": "fun" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "ParamRef", "__tag": 4071, "name": "grad" }, { "__type": "Text", "__tag": 4046, "value": ", hess` and corresponding attributes " }, { "__type": "InlineRole", "__tag": 4003, "value": "f", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineRole", "__tag": 4003, "value": "g", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineRole", "__tag": 4003, "value": "H", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ". The following things should be considered:" } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "BulletList", "__tag": 4053, "ordered": true, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Use only public methods " }, { "__type": "ParamRef", "__tag": 4071, "name": "fun" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "ParamRef", "__tag": 4071, "name": "grad" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "ParamRef", "__tag": 4071, "name": "hess" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "After one of the methods is called, the corresponding attribute will be set. However, a subsequent call with a different argument of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "any" } ] }, { "__type": "Text", "__tag": 4046, "value": " of the methods may overwrite the attribute." } ] } ] } ] } ] } ], "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": [], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Scalar function and its derivatives." } ] } ], "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": "fun", "annotation": "callable", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "evaluates the scalar function. Must be of the form " }, { "__type": "InlineCode", "__tag": 4051, "value": "fun(x, *args)" }, { "__type": "Text", "__tag": 4046, "value": ", where " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": " is the argument in the form of a 1-D array and " }, { "__type": "InlineCode", "__tag": 4051, "value": "args" }, { "__type": "Text", "__tag": 4046, "value": " is a tuple of any additional fixed parameters needed to completely specify the function. Should return a scalar." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "x0", "annotation": "array-like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Provides an initial set of variables for evaluating fun. Array of real elements of size (n,), where 'n' is the number of independent variables." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "args", "annotation": "tuple, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Any additional fixed parameters needed to completely specify the scalar function." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "grad", "annotation": "{callable, '2-point', '3-point', 'cs'}", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Method for computing the gradient vector. If it is a callable, it should be a function that returns the gradient vector:" } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "grad(x, *args) -> array_like, shape (n,)" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "where " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": " is an array with shape (n,) and " }, { "__type": "InlineCode", "__tag": 4051, "value": "args" }, { "__type": "Text", "__tag": 4046, "value": " is a tuple with the fixed parameters. Alternatively, the keywords {'2-point', '3-point', 'cs'} can be used to select a finite difference scheme for numerical estimation of the gradient with a relative step size. These finite difference schemes obey any specified " }, { "__type": "InlineRole", "__tag": 4003, "value": "bounds", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "hess", "annotation": "{callable, '2-point', '3-point', 'cs', HessianUpdateStrategy}", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Method for computing the Hessian matrix. If it is callable, it should return the Hessian matrix:" } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "hess(x, *args) -> {LinearOperator, spmatrix, array}, (n, n)" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "where x is a (n,) ndarray and " }, { "__type": "ParamRef", "__tag": 4071, "name": "args" }, { "__type": "Text", "__tag": 4046, "value": " is a tuple with the fixed parameters. Alternatively, the keywords {'2-point', '3-point', 'cs'} select a finite difference scheme for numerical estimation. Or, objects implementing " }, { "__type": "CrossRef", "__tag": 4002, "value": "HessianUpdateStrategy", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.optimize._hessian_update_strategy:HessianUpdateStrategy" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " interface can be used to approximate the Hessian. Whenever the gradient is estimated via finite-differences, the Hessian cannot be estimated with options {'2-point', '3-point', 'cs'} and needs to be estimated using one of the quasi-Newton strategies." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "finite_diff_rel_step", "annotation": "None or array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Relative step size to use. The absolute step size is computed as " }, { "__type": "InlineCode", "__tag": 4051, "value": "h = finite_diff_rel_step * sign(x0) * max(1, abs(x0))" }, { "__type": "Text", "__tag": 4046, "value": ", possibly adjusted to fit into the bounds. For " }, { "__type": "InlineCode", "__tag": 4051, "value": "method='3-point'" }, { "__type": "Text", "__tag": 4046, "value": " the sign of " }, { "__type": "InlineRole", "__tag": 4003, "value": "h", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " is ignored. If None then finite_diff_rel_step is selected automatically," } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "finite_diff_bounds", "annotation": "tuple of array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Lower and upper bounds on independent variables. Defaults to no bounds, (-np.inf, np.inf). Each bound must match the size of " }, { "__type": "ParamRef", "__tag": 4071, "name": "x0" }, { "__type": "Text", "__tag": 4046, "value": " or be a scalar, in the latter case the bound will be the same for all variables. Use it to limit the range of function evaluation." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "epsilon", "annotation": "None or array_like, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Absolute step size to use, possibly adjusted to fit into the bounds. For " }, { "__type": "InlineCode", "__tag": 4051, "value": "method='3-point'" }, { "__type": "Text", "__tag": 4046, "value": " the sign of " }, { "__type": "ParamRef", "__tag": 4071, "name": "epsilon" }, { "__type": "Text", "__tag": 4046, "value": " is ignored. By default relative steps are used, only if " }, { "__type": "InlineCode", "__tag": 4051, "value": "epsilon is not None" }, { "__type": "Text", "__tag": 4046, "value": " are absolute steps used." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "workers", "annotation": "map-like callable, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A map-like callable, such as " }, { "__type": "InlineRole", "__tag": 4003, "value": "multiprocessing.Pool.map", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " for evaluating any numerical differentiation in parallel. This evaluation is carried out as " }, { "__type": "InlineCode", "__tag": 4051, "value": "workers(fun, iterable)" }, { "__type": "Text", "__tag": 4046, "value": ", or " }, { "__type": "InlineCode", "__tag": 4051, "value": "workers(grad, iterable)" }, { "__type": "Text", "__tag": 4046, "value": ", depending on what is being numerically differentiated. Alternatively, if " }, { "__type": "ParamRef", "__tag": 4071, "name": "workers" }, { "__type": "Text", "__tag": 4046, "value": " is an int the task is subdivided into " }, { "__type": "ParamRef", "__tag": 4071, "name": "workers" }, { "__type": "Text", "__tag": 4046, "value": " sections and the function evaluated in parallel (uses " }, { "__type": "InlineRole", "__tag": 4003, "value": "multiprocessing.Pool ", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "). Supply -1 to use all available CPU cores. It is recommended that a map-like be used instead of int, as repeated calls to " }, { "__type": "CrossRef", "__tag": 4002, "value": "approx_derivative", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.optimize._numdiff:approx_derivative" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " will incur large overhead from setting up new processes." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 1.16.0" } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This class defines a scalar function F: R^n->R and methods for computing or approximating its first and second derivatives." } ] } ], "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/_differentiable_functions.py", "item_line": 128, "item_type": "class", "aliases": [ "scipy.optimize._differentiable_functions.ScalarFunction" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "see_also": [], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "fun", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "x0", "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": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "grad", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "hess", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "finite_diff_rel_step", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "finite_diff_bounds", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "(-inf, inf)" }, { "__type": "SigParam", "__tag": 4030, "name": "epsilon", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "workers", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "ScalarFunction" }, "references": null, "qa": "scipy.optimize._differentiable_functions:ScalarFunction", "arbitrary": [], "local_refs": [ "args", "epsilon", "finite_diff_bounds", "finite_diff_rel_step", "fun", "grad", "hess", "workers", "x0" ] }