{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The Tits and Yang (YT), " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": " paper is an update of the original Kautsky et al. (KNV) paper " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": ". KNV relies on rank-1 updates to find the transfer matrix X such that " }, { "__type": "InlineCode", "__tag": 4051, "value": "X * diag(poles) = (A - B*K)*X" }, { "__type": "Text", "__tag": 4046, "value": ", whereas YT uses rank-2 updates. This yields on average more robust solutions (see " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": " pp 21-22), furthermore the YT algorithm supports complex poles whereas KNV does not in its original version. Only update method 0 proposed by KNV has been implemented here, hence the name " }, { "__type": "InlineCode", "__tag": 4051, "value": "'KNV0'" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "KNV extended to complex poles is used in Matlab's " }, { "__type": "InlineCode", "__tag": 4051, "value": "place" }, { "__type": "Text", "__tag": 4046, "value": " function, YT is distributed under a non-free licence by Slicot under the name " }, { "__type": "InlineCode", "__tag": 4051, "value": "robpole" }, { "__type": "Text", "__tag": 4046, "value": ". It is unclear and undocumented how KNV0 has been extended to complex poles (Tits and Yang claim on page 14 of their paper that their method can not be used to extend KNV to complex poles), therefore only YT supports them in this implementation." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "As the solution to the problem of pole placement is not unique for MIMO systems, both methods start with a tentative transfer matrix which is altered in various way to increase its determinant. Both methods have been proven to converge to a stable solution, however depending on the way the initial transfer matrix is chosen they will converge to different solutions and therefore there is absolutely no guarantee that using " }, { "__type": "InlineCode", "__tag": 4051, "value": "'KNV0'" }, { "__type": "Text", "__tag": 4046, "value": " will yield results similar to Matlab's or any other implementation of these algorithms." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Using the default method " }, { "__type": "InlineCode", "__tag": 4051, "value": "'YT'" }, { "__type": "Text", "__tag": 4046, "value": " should be fine in most cases; " }, { "__type": "InlineCode", "__tag": 4051, "value": "'KNV0'" }, { "__type": "Text", "__tag": 4046, "value": " is only provided because it is needed by " }, { "__type": "InlineCode", "__tag": 4051, "value": "'YT'" }, { "__type": "Text", "__tag": 4046, "value": " in some specific cases. Furthermore " }, { "__type": "InlineCode", "__tag": 4051, "value": "'YT'" }, { "__type": "Text", "__tag": 4046, "value": " gives on average more robust results than " }, { "__type": "InlineCode", "__tag": 4051, "value": "'KNV0'" }, { "__type": "Text", "__tag": 4046, "value": " when " }, { "__type": "InlineCode", "__tag": 4051, "value": "abs(det(X))" }, { "__type": "Text", "__tag": 4046, "value": " is used as a robustness indicator." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": " is available as a technical report on the following URL: https://hdl.handle.net/1903/5598" } ] }, { "__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": "place_poles", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._ltisys:place_poles" }, "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 }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "See " }, { "__type": "InlineRole", "__tag": 4003, "value": "dev-arrayapi", "domain": null, "role": "ref", "inventory": null }, { "__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": "full_state_feedback", "annotation": "Bunch object", "desc": [ { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "full_state_feedback is composed of:" } ] }, "dd": [ { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "gain_matrix" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "gain_matrix" } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "computed_poles" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "computed_poles" } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "requested_poles" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "requested_poles" } ] } ] }, { "__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": "X" } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "rtol" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "rtol" } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "nb_iter" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "nb_iter" } ] } ] } ] } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Compute K such that eigenvalues (A - dot(B, K))=poles." } ] } ], "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": "A, B", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "State-space representation of linear system " }, { "__type": "InlineCode", "__tag": 4051, "value": "AX + BU" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "poles", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Desired real poles and/or complex conjugates poles. Complex poles are only supported with " }, { "__type": "InlineCode", "__tag": 4051, "value": "method=\"YT\"" }, { "__type": "Text", "__tag": 4046, "value": " (default)." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "method: {'YT', 'KNV0'}, optional", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Which method to choose to find the gain matrix K. One of:" } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'YT': Yang Tits" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'KNV0': Kautsky, Nichols, Van Dooren update method 0" } ] } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "See References and Notes for details on the algorithms." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "rtol: float, optional", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "After each iteration the determinant of the eigenvectors of " }, { "__type": "InlineCode", "__tag": 4051, "value": "A - B*K" }, { "__type": "Text", "__tag": 4046, "value": " is compared to its previous value, when the relative error between these two values becomes lower than " }, { "__type": "ParamRef", "__tag": 4071, "name": "rtol" }, { "__type": "Text", "__tag": 4046, "value": " the algorithm stops. Default is 1e-3." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "maxiter: int, optional", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Maximum number of iterations to compute the gain matrix. Default is 30." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "K is the gain matrix such as the plant described by the linear system " }, { "__type": "InlineCode", "__tag": 4051, "value": "AX+BU" }, { "__type": "Text", "__tag": 4046, "value": " will have its closed-loop poles, i.e the eigenvalues " }, { "__type": "InlineCode", "__tag": 4051, "value": "A - B*K" }, { "__type": "Text", "__tag": 4046, "value": ", as close as possible to those asked for in poles." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "SISO, MISO and MIMO systems are supported." } ] } ], "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/signal/_ltisys.py", "item_line": 2689, "item_type": "function", "aliases": [ "scipy.signal.place_poles" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "A simple example demonstrating real pole placement using both KNV and YT\nalgorithms. This is example number 1 from section 4 of the reference KNV\npublication ([1]_):\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy import signal\nimport matplotlib.pyplot as plt\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "A = np.array([[ 1.380, -0.2077, 6.715, -5.676 ],\n [-0.5814, -4.290, 0, 0.6750 ],\n [ 1.067, 4.273, -6.654, 5.893 ],\n [ 0.0480, 4.273, 1.343, -2.104 ]])\nB = np.array([[ 0, 5.679 ],\n [ 1.136, 1.136 ],\n [ 0, 0, ],\n [-3.146, 0 ]])\nP = np.array([-0.2, -0.5, -5.0566, -8.6659])\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nNow compute K with KNV method 0, with the default YT method and with the YT\nmethod while forcing 100 iterations of the algorithm and print some results\nafter each call.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "fsf1 = signal.place_poles(A, B, P, method='KNV0')\nfsf1.gain_matrix\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "fsf2 = signal.place_poles(A, B, P) # uses YT method\nfsf2.computed_poles\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "fsf3 = signal.place_poles(A, B, P, rtol=-1, maxiter=100)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "fsf3.X\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nThe absolute value of the determinant of X is a good indicator to check the\nrobustness of the results, both ``'KNV0'`` and ``'YT'`` aim at maximizing\nit. Below a comparison of the robustness of the results above:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "abs(np.linalg.det(fsf1.X)) < abs(np.linalg.det(fsf2.X))\nabs(np.linalg.det(fsf2.X)) < abs(np.linalg.det(fsf3.X))\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nNow a simple example for complex poles:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "A = np.array([[ 0, 7/3., 0, 0 ],\n [ 0, 0, 0, 7/9. ],\n [ 0, 0, 0, 0 ],\n [ 0, 0, 0, 0 ]])\nB = np.array([[ 0, 0 ],\n [ 0, 0 ],\n [ 1, 0 ],\n [ 0, 1 ]])\nP = np.array([-3, -1, -2-1j, -2+1j]) / 3.\nfsf = signal.place_poles(A, B, P, method='YT')\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nWe can plot the desired and computed poles in the complex plane:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "t = np.linspace(0, 2*np.pi, 401)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "plt.plot(np.cos(t), np.sin(t), 'k--') # unit circle\nplt.plot(fsf.requested_poles.real, fsf.requested_poles.imag,\n 'wo', label='Desired')\nplt.plot(fsf.computed_poles.real, fsf.computed_poles.imag, 'bx',\n label='Placed')\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "plt.grid()\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "plt.axis('image')\nplt.axis([-1.1, 1.1, -1.1, 1.1])\nplt.legend(bbox_to_anchor=(1.05, 1), loc=2, numpoints=1)\n", "execution_status": "failure" } ], "title": [], "level": 0, "target": null }, "see_also": [], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "A", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "B", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "poles", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "method", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "YT" }, { "__type": "SigParam", "__tag": 4030, "name": "rtol", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "0.001" }, { "__type": "SigParam", "__tag": 4030, "name": "maxiter", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "30" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "place_poles" }, "references": [ ".. [1] J. Kautsky, N.K. Nichols and P. van Dooren, \"Robust pole assignment", " in linear state feedback\", International Journal of Control, Vol. 41", " pp. 1129-1155, 1985.", ".. [2] A.L. Tits and Y. Yang, \"Globally convergent algorithms for robust", " pole assignment by state feedback\", IEEE Transactions on Automatic", " Control, Vol. 41, pp. 1432-1452, 1996." ], "qa": "scipy.signal._ltisys:place_poles", "arbitrary": [], "local_refs": [ "'KNV0'}", "A", "B", "full_state_feedback", "maxiter: int", "method: {'YT'", "optional", "poles", "rtol: float" ] }