{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This algorithm is based on linear approximations to the objective function and each constraint. We briefly describe the algorithm." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Suppose the function is being minimized over k variables. At the jth iteration the algorithm has k+1 points v_1, ..., v_(k+1), an approximate solution x_j, and a radius RHO_j. (i.e., linear plus a constant) approximations to the objective function and constraint functions such that their function values agree with the linear approximation on the k+1 points v_1,.., v_(k+1). This gives a linear program to solve (where the linear approximations of the constraint functions are constrained to be non-negative)." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "However, the linear approximations are likely only good approximations near the current simplex, so the linear program is given the further requirement that the solution, which will become x_(j+1), must be within RHO_j from x_j. RHO_j only decreases, never increases. The initial RHO_j is rhobeg and the final RHO_j is rhoend. In this way COBYLA's iterations behave like a trust region algorithm." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Additionally, the linear program may be inconsistent, or the approximation may give poor improvement. For details about how these issues are resolved, as well as how the points v_i are updated, refer to the source code or the references below." } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Admonition", "__tag": 4056, "kind": "versionchanged", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionchanged 1.16.0" } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The original Powell implementation was replaced by a pure" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Python version from the PRIMA package, with bug fixes and improvements being made." } ] } ] } ] } ] } ] } ], "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": "x", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The argument that minimises " }, { "__type": "InlineRole", "__tag": 4003, "value": "f", "domain": null, "role": null, "inventory": null }, { "__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": "Minimize a function using the Constrained Optimization By Linear Approximation (COBYLA) method. This method uses the pure-python implementation of the algorithm from PRIMA." } ] } ], "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": "func", "annotation": "callable", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Function to minimize. In the form func(x, *args)." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "x0", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Initial guess." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "cons", "annotation": "sequence", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Constraint functions; must all be " }, { "__type": "InlineCode", "__tag": 4051, "value": ">=0" }, { "__type": "Text", "__tag": 4046, "value": " (a single function if only 1 constraint). Each function takes the parameters " }, { "__type": "CrossRef", "__tag": 4002, "value": "x", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "x" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": " as its first argument, and it can return either a single number or an array or list of numbers." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "args", "annotation": "tuple, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Extra arguments to pass to function." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "consargs", "annotation": "tuple, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Extra arguments to pass to constraint functions (default of None means use same extra arguments as those passed to func). Use " }, { "__type": "InlineCode", "__tag": 4051, "value": "()" }, { "__type": "Text", "__tag": 4046, "value": " for no extra arguments." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "rhobeg", "annotation": "float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Reasonable initial changes to the variables." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "rhoend", "annotation": "float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Final accuracy in the optimization (not precisely guaranteed). This is a lower bound on the size of the trust region." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "disp", "annotation": "{0, 1, 2, 3}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Controls the frequency of output; 0 implies no output." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "maxfun", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Maximum number of function evaluations." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "catol", "annotation": "float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Absolute tolerance for constraint violations." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "callback", "annotation": "callable, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Called after each iteration, as " }, { "__type": "InlineCode", "__tag": 4051, "value": "callback(x)" }, { "__type": "Text", "__tag": 4046, "value": ", where " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": " is the current parameter vector." } ] } ] } ] } ], "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/_cobyla_py.py", "item_line": 23, "item_type": "function", "aliases": [ "scipy.optimize.fmin_cobyla" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "Minimize the objective function f(x,y) = x*y subject\nto the constraints x**2 + y**2 < 1 and y > 0::\n\n" }, { "__type": "Code", "__tag": 4050, "value": "def objective(x):\n return x[0]*x[1]\ndef constr1(x):\n return 1 - (x[0]**2 + x[1]**2)\ndef constr2(x):\n return x[1]\nfrom scipy.optimize import fmin_cobyla\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "fmin_cobyla(objective, [0.0, 0.1], [constr1, constr2], rhoend=1e-7)\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nThe exact solution is (-sqrt(2)/2, sqrt(2)/2)." } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "minimize", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "minimize" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Interface to minimization algorithms for multivariate functions. See the 'COBYLA' " }, { "__type": "InlineRole", "__tag": 4003, "value": "method", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " in particular." } ] } ], "type": null } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "func", "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": "cons", "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": "consargs", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "rhobeg", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "1.0" }, { "__type": "SigParam", "__tag": 4030, "name": "rhoend", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "0.0001" }, { "__type": "SigParam", "__tag": 4030, "name": "maxfun", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "1000" }, { "__type": "SigParam", "__tag": 4030, "name": "disp", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "catol", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "0.0002" }, { "__type": "SigParam", "__tag": 4030, "name": "callback", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "fmin_cobyla" }, "references": [ "Powell M.J.D. (1994), \"A direct search optimization method that models", "the objective and constraint functions by linear interpolation.\", in", "Advances in Optimization and Numerical Analysis, eds. S. Gomez and", "J-P Hennart, Kluwer Academic (Dordrecht), pp. 51-67", "", "Powell M.J.D. (1998), \"Direct search algorithms for optimization", "calculations\", Acta Numerica 7, 287-336", "", "Powell M.J.D. (2007), \"A view of algorithms for optimization without", "derivatives\", Cambridge University Technical Report DAMTP 2007/NA03", "", "Zhang Z. (2023), \"PRIMA: Reference Implementation for Powell's Methods with", "Modernization and Amelioration\", https://www.libprima.net,", ":doi:`10.5281/zenodo.8052654`" ], "qa": "scipy.optimize._cobyla_py:fmin_cobyla", "arbitrary": [], "local_refs": [ "args", "callback", "catol", "cons", "consargs", "disp", "func", "maxfun", "rhobeg", "rhoend", "x", "x0" ] }