{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Assuming that " }, { "__type": "InlineMath", "__tag": 4057, "value": "f\\in C^{3}" }, { "__type": "Text", "__tag": 4046, "value": " (i.e., " }, { "__type": "InlineMath", "__tag": 4057, "value": "f" }, { "__type": "Text", "__tag": 4046, "value": " has at least 3 continuous derivatives) and let " }, { "__type": "InlineMath", "__tag": 4057, "value": "h_{*}" }, { "__type": "Text", "__tag": 4046, "value": " be a non-homogeneous stepsize, we minimize the \"consistency error\" " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\eta_{i}" }, { "__type": "Text", "__tag": 4046, "value": " between the true gradient and its estimate from a linear combination of the neighboring grid-points:" } ] }, { "__type": "Math", "__tag": 4058, "value": "\\eta_{i} = f_{i}^{\\left(1\\right)} -\n \\left[ \\alpha f\\left(x_{i}\\right) +\n \\beta f\\left(x_{i} + h_{d}\\right) +\n \\gamma f\\left(x_{i}-h_{s}\\right)\n \\right]" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "By substituting " }, { "__type": "InlineMath", "__tag": 4057, "value": "f(x_{i} + h_{d})" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineMath", "__tag": 4057, "value": "f(x_{i} - h_{s})" }, { "__type": "Text", "__tag": 4046, "value": " with their Taylor series expansion, this translates into solving the following the linear system:" } ] }, { "__type": "Math", "__tag": 4058, "value": "\\left\\{\n \\begin{array}{r}\n \\alpha+\\beta+\\gamma=0 \\\\\n \\beta h_{d}-\\gamma h_{s}=1 \\\\\n \\beta h_{d}^{2}+\\gamma h_{s}^{2}=0\n \\end{array}\n\\right." }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The resulting approximation of " }, { "__type": "InlineMath", "__tag": 4057, "value": "f_{i}^{(1)}" }, { "__type": "Text", "__tag": 4046, "value": " is the following:" } ] }, { "__type": "Math", "__tag": 4058, "value": "\\hat f_{i}^{(1)} =\n \\frac{\n h_{s}^{2}f\\left(x_{i} + h_{d}\\right)\n + \\left(h_{d}^{2} - h_{s}^{2}\\right)f\\left(x_{i}\\right)\n - h_{d}^{2}f\\left(x_{i}-h_{s}\\right)}\n { h_{s}h_{d}\\left(h_{d} + h_{s}\\right)}\n + \\mathcal{O}\\left(\\frac{h_{d}h_{s}^{2}\n + h_{s}h_{d}^{2}}{h_{d}\n + h_{s}}\\right)" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "It is worth noting that if " }, { "__type": "InlineMath", "__tag": 4057, "value": "h_{s}=h_{d}" }, { "__type": "Text", "__tag": 4046, "value": " (i.e., data are evenly spaced) we find the standard second order approximation:" } ] }, { "__type": "Math", "__tag": 4058, "value": "\\hat f_{i}^{(1)}=\n \\frac{f\\left(x_{i+1}\\right) - f\\left(x_{i-1}\\right)}{2h}\n + \\mathcal{O}\\left(h^{2}\\right)" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "With a similar procedure the forward/backward approximations used for boundaries can be derived." } ] } ], "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": "gradient", "annotation": "ndarray or tuple of ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A tuple of ndarrays (or a single ndarray if there is only one dimension) corresponding to the derivatives of f with respect to each dimension. Each derivative has the same shape as f." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Return the gradient of an N-dimensional array." } ] } ], "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": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An N-dimensional array containing samples of a scalar function." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "varargs", "annotation": "list of scalar or array, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Spacing between f values. Default unitary spacing for all dimensions. Spacing can be specified using:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": true, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "single scalar to specify a sample distance for all dimensions." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "N scalars to specify a constant sample distance for each dimension. i.e. " }, { "__type": "InlineRole", "__tag": 4003, "value": "dx", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineRole", "__tag": 4003, "value": "dy", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineRole", "__tag": 4003, "value": "dz", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", ..." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "N arrays to specify the coordinates of the values along each dimension of F. The length of the array must match the size of the corresponding dimension" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Any combination of N scalars/arrays with the meaning of 2. and 3." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "ParamRef", "__tag": 4071, "name": "axis" }, { "__type": "Text", "__tag": 4046, "value": " is given, the number of varargs must equal the number of axes specified in the axis parameter. Default: 1. (see Examples below)." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "edge_order", "annotation": "{1, 2}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Gradient is calculated using N-th order accurate differences at the boundaries. Default: 1." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "axis", "annotation": "None or int or tuple of ints, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Gradient is calculated only along the given axis or axes The default (axis = None) is to calculate the gradient for all the axes of the input array. axis may be negative, in which case it counts from the last to the first axis." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The gradient is computed using second order accurate central differences in the interior points and either first or second order accurate one-sides (forward or backwards) differences at the boundaries. The returned gradient hence has the same shape as the input array." } ] } ], "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/lib/_function_base_impl.py", "item_line": 1002, "item_type": "_ArrayFunctionDispatcher", "aliases": [ "numpy.gradient" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nf = np.array([1, 2, 4, 7, 11, 16])\nnp.gradient(f)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "np.gradient(f, 2)\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nSpacing can be also specified with an array that represents the coordinates\nof the values F along the dimensions.\nFor instance a uniform spacing:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "x = np.arange(f.size)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "np.gradient(f, x)\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nOr a non uniform one:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "x = np.array([0., 1., 1.5, 3.5, 4., 6.])\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "np.gradient(f, x)\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nFor two dimensional arrays, the return will be two arrays ordered by\naxis. In this example the first array stands for the gradient in\nrows and the second one in columns direction:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "np.gradient(np.array([[1, 2, 6], [3, 4, 5]]))\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nIn this example the spacing is also specified:\nuniform for axis=0 and non uniform for axis=1\n\n" }, { "__type": "Code", "__tag": 4050, "value": "dx = 2.\ny = [1., 1.5, 3.5]\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "np.gradient(np.array([[1, 2, 6], [3, 4, 5]]), dx, y)\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nIt is possible to specify how boundaries are treated using `edge_order`\n\n" }, { "__type": "Code", "__tag": 4050, "value": "x = np.array([0, 1, 2, 3, 4])\nf = x**2\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "np.gradient(f, edge_order=1)\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "np.gradient(f, edge_order=2)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe `axis` keyword can be used to specify a subset of axes of which the\ngradient is calculated\n\n" }, { "__type": "Code", "__tag": 4050, "value": "np.gradient(np.array([[1, 2, 6], [3, 4, 5]]), axis=0)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe `varargs` argument defines the spacing between sample points in the\ninput array. It can take two forms:\n\n1. An array, specifying coordinates, which may be unevenly spaced:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "x = np.array([0., 2., 3., 6., 8.])\ny = x ** 2\nnp.gradient(y, x, edge_order=2)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\n2. A scalar, representing the fixed sample distance:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "dx = 2\nx = np.array([0., 2., 4., 6., 8.])\ny = x ** 2\nnp.gradient(y, dx, edge_order=2)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nIt's possible to provide different data for spacing along each dimension.\nThe number of arguments must match the number of dimensions in the input\ndata.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "dx = 2\ndy = 3\nx = np.arange(0, 6, dx)\ny = np.arange(0, 9, dy)\nxs, ys = np.meshgrid(x, y)\nzs = xs + 2 * ys\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "np.gradient(zs, dy, dx) # Passing two scalars\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nMixing scalars and arrays is also allowed:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "np.gradient(zs, y, dx) # Passing one array and one scalar\n", "execution_status": "failure" } ], "title": [], "level": 0, "target": null }, "see_also": [], "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": "varargs", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "VAR_POSITIONAL", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "axis", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "edge_order", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "1" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "gradient" }, "references": [ ".. [1] Quarteroni A., Sacco R., Saleri F. (2007) Numerical Mathematics", " (Texts in Applied Mathematics). New York: Springer.", ".. [2] Durran D. R. (1999) Numerical Methods for Wave Equations", " in Geophysical Fluid Dynamics. New York: Springer.", ".. [3] Fornberg B. (1988) Generation of Finite Difference Formulas on", " Arbitrarily Spaced Grids,", " Mathematics of Computation 51, no. 184 : 699-706.", " `PDF `_." ], "qa": "numpy:gradient", "arbitrary": [], "local_refs": [ "axis", "edge_order", "f", "gradient", "varargs" ] }