{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Warns": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Raises": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "", "annotation": "ValueError", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If the dimension of " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": " is less than 2." } ] } ] } ] } ], "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": "array_of_diagonals", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": " is 2-D, then a 1-D array containing the diagonal and of the same type as " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": " is returned unless " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": " is a " }, { "__type": "InlineRole", "__tag": 4003, "value": "matrix", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", in which case a 1-D array rather than a (2-D) " }, { "__type": "InlineRole", "__tag": 4003, "value": "matrix", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " is returned in order to maintain backward compatibility." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "InlineCode", "__tag": 4051, "value": "a.ndim > 2" }, { "__type": "Text", "__tag": 4046, "value": ", then the dimensions specified by " }, { "__type": "ParamRef", "__tag": 4071, "name": "axis1" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "ParamRef", "__tag": 4071, "name": "axis2" }, { "__type": "Text", "__tag": 4046, "value": " are removed, and a new axis inserted at the end corresponding to the diagonal." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Return specified diagonals." } ] } ], "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", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Array from which the diagonals are taken." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "offset", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Offset of the diagonal from the main diagonal. Can be positive or negative. Defaults to main diagonal (0)." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "axis1", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Axis to be used as the first axis of the 2-D sub-arrays from which the diagonals should be taken. Defaults to first axis (0)." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "axis2", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Axis to be used as the second axis of the 2-D sub-arrays from which the diagonals should be taken. Defaults to second axis (1)." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": " is 2-D, returns the diagonal of " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": " with the given offset, i.e., the collection of elements of the form " }, { "__type": "InlineCode", "__tag": 4051, "value": "a[i, i+offset]" }, { "__type": "Text", "__tag": 4046, "value": ". If " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": " has more than two dimensions, then the axes specified by " }, { "__type": "ParamRef", "__tag": 4071, "name": "axis1" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "ParamRef", "__tag": 4071, "name": "axis2" }, { "__type": "Text", "__tag": 4046, "value": " are used to determine the 2-D sub-array whose diagonal is returned. The shape of the resulting array can be determined by removing " }, { "__type": "ParamRef", "__tag": 4071, "name": "axis1" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "ParamRef", "__tag": 4071, "name": "axis2" }, { "__type": "Text", "__tag": 4046, "value": " and appending an index to the right equal to the size of the resulting diagonals." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In versions of NumPy prior to 1.7, this function always returned a new, independent array containing a copy of the values in the diagonal." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In NumPy 1.7 and 1.8, it continues to return a copy of the diagonal, but depending on this fact is deprecated. Writing to the resulting array continues to work as it used to, but a FutureWarning is issued." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Starting in NumPy 1.9 it returns a read-only view on the original array. Attempting to write to the resulting array will produce an error." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In some future release, it will return a read/write view and writing to the returned array will alter your original array. The returned array will have the same type as the input array." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If you don't write to the array returned by this function, then you can just ignore all of the above." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If you depend on the current behavior, then we suggest copying the returned array explicitly, i.e., use " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.diagonal(a).copy()" }, { "__type": "Text", "__tag": 4046, "value": " instead of just " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.diagonal(a)" }, { "__type": "Text", "__tag": 4046, "value": ". This will work with both past and future versions of NumPy." } ] } ], "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": "/dev/numpy/build-install/usr/lib/python3.14/site-packages/numpy/_core/fromnumeric.py", "item_line": 1670, "item_type": "_ArrayFunctionDispatcher", "aliases": [ "numpy.diagonal" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "import numpy as np\na = np.arange(4).reshape(2,2)\na\na.diagonal()\na.diagonal(1)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nA 3-D example:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "a = np.arange(8).reshape(2,2,2); a\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "a.diagonal(0, # Main diagonals of two arrays created by skipping\n 0, # across the outer(left)-most axis last and\n 1) # the \"middle\" (row) axis first.\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe sub-arrays whose main diagonals we just obtained; note that each\ncorresponds to fixing the right-most (column) axis, and that the\ndiagonals are \"packed\" in rows.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "a[:,:,0] # main diagonal is [0 6]\na[:,:,1] # main diagonal is [1 7]\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe anti-diagonal can be obtained by reversing the order of elements\nusing either `numpy.flipud` or `numpy.fliplr`.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "a = np.arange(9).reshape(3, 3)\na\nnp.fliplr(a).diagonal() # Horizontal flip\nnp.flipud(a).diagonal() # Vertical flip\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nNote that the order in which the diagonal is retrieved varies depending\non the flip function." } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "diag", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy:diagonal" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "MATLAB work-a-like for 1-D and 2-D arrays." } ] } ], "type": null }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "diagflat", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "diagflat" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Create diagonal arrays." } ] } ], "type": null }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "trace", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "trace" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Sum along diagonals." } ] } ], "type": null } ], "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": "offset", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "0" }, { "__type": "SigParam", "__tag": 4030, "name": "axis1", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "0" }, { "__type": "SigParam", "__tag": 4030, "name": "axis2", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "1" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "diagonal" }, "references": null, "qa": "numpy:diagonal", "arbitrary": [], "local_refs": [ "a", "array_of_diagonals", "axis1", "axis2", "offset" ] }