{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "sparse" } ], "url": "https://sparse.pydata.org/", "title": "" }, { "__type": "Text", "__tag": 4046, "value": ", as well as read-only arrays from libraries not explicitly covered by " }, { "__type": "InlineCode", "__tag": 4051, "value": "array-api-compat" }, { "__type": "Text", "__tag": 4046, "value": ", are not supported by update methods." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Boolean masks are supported on Dask and jitted JAX arrays exclusively when " }, { "__type": "ParamRef", "__tag": 4071, "name": "idx" }, { "__type": "Text", "__tag": 4046, "value": " has the same shape as " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineRole", "__tag": 4003, "value": "y", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " is 0-dimensional. Note that this support is not available in JAX's native " }, { "__type": "InlineCode", "__tag": 4051, "value": "x.at[mask].set(y)" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This pattern " } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> mask = m(x)\n>>> x[mask] = f(x[mask])", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Can't be replaced by " }, { "__type": "CrossRef", "__tag": 4002, "value": "at", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy._lib.array_api_extra._lib._at:at" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ", as it won't work on Dask and JAX inside jax.jit " } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> mask = m(x)\n>>> x = xpx.at(x, mask).set(f(x[mask]) # Crash on Dask and jax.jit", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "You should instead use " } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> x = xp.where(m(x), f(x), x)", "execution_status": null } ], "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": "", "annotation": "Updated input array.", "desc": [] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Update operations for read-only arrays." } ] } ], "title": [], "level": 0, "target": null }, "Receives": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Warnings": { "__type": "Section", "__tag": 4015, "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": "When you omit the " }, { "__type": "InlineCode", "__tag": 4051, "value": "copy" }, { "__type": "Text", "__tag": 4046, "value": " parameter, you should never reuse the parameter" } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "array later on; ideally, you should reassign it immediately " } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> import array_api_extra as xpx\n>>> x = xpx.at(x, 0).set(2)", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The above best practice pattern ensures that the behaviour won't change depending on whether " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": " is writeable or not, as the original " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": " object is dereferenced as soon as " }, { "__type": "InlineCode", "__tag": 4051, "value": "xpx.at" }, { "__type": "Text", "__tag": 4046, "value": " returns; this way there is no risk to accidentally update it twice." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "On the reverse, the anti-pattern below must be avoided, as it will result in different behaviour on read-only versus writeable arrays " } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> x = xp.asarray([0, 0, 0])\n>>> y = xpx.at(x, 0).set(2)\n>>> z = xpx.at(x, 1).set(3)", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In the above example, both calls to " }, { "__type": "InlineCode", "__tag": 4051, "value": "xpx.at" }, { "__type": "Text", "__tag": 4046, "value": " update " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": " in place " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "if possible" } ] }, { "__type": "Text", "__tag": 4046, "value": ". This causes the behaviour to diverge depending on whether " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": " is writeable or not:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": " is writeable, then after the snippet above you'll have " }, { "__type": "InlineCode", "__tag": 4051, "value": "x == y == z == [2, 3, 0]" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": " is read-only, then you'll end up with " }, { "__type": "InlineCode", "__tag": 4051, "value": "x == [0, 0, 0]" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "y == [2, 0, 0]" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "z == [0, 3, 0]" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The correct pattern to use if you want diverging outputs from the same input is to enforce copies " } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> x = xp.asarray([0, 0, 0])\n>>> y = xpx.at(x, 0).set(2, copy=True) # Never updates x\n>>> z = xpx.at(x, 1).set(3) # May or may not update x in place\n>>> del x # avoid accidental reuse of x as we don't know its state anymore", "execution_status": null }, { "__type": "BulletList", "__tag": 4053, "ordered": true, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The array API standard does not support integer array indices." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The behaviour of update methods when the index is an array of integers is undefined and will vary between backends; this is particularly true when the index contains multiple occurrences of the same index, e.g. " } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> import numpy as np\n>>> import jax.numpy as jnp\n>>> import array_api_extra as xpx\n>>> xpx.at(np.asarray([123]), np.asarray([0, 0])).add(1)\narray([124])\n>>> xpx.at(jnp.asarray([123]), jnp.asarray([0, 0])).add(1)\nArray([125], dtype=int32)", "execution_status": null } ], "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": "x", "annotation": "array", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Input array." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "idx", "annotation": "index, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Only " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "array API standard compliant indices" } ], "url": "https://data-apis.org/array-api/latest/API_specification/indexing.html", "title": "" }, { "__type": "Text", "__tag": 4046, "value": " are supported." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "You may use two alternate syntaxes " } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> import array_api_extra as xpx\n>>> xpx.at(x, idx).set(value) # or add(value), etc.\n>>> xpx.at(x)[idx].set(value)", "execution_status": null } ] }, { "__type": "DocParam", "__tag": 4016, "name": "copy", "annotation": "bool, optional", "desc": [ { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "None (default)" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The array parameter " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "may" } ] }, { "__type": "Text", "__tag": 4046, "value": " be modified in place if it is possible and beneficial for performance. You should not reuse it after calling this function." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "True" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Ensure that the inputs are not modified." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "False" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Ensure that the update operation writes back to the input. Raise " }, { "__type": "InlineCode", "__tag": 4051, "value": "ValueError" }, { "__type": "Text", "__tag": 4046, "value": " if a copy cannot be avoided." } ] } ] } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "xp", "annotation": "array_namespace, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The standard-compatible namespace for " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": ". Default: infer." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This implements " }, { "__type": "InlineCode", "__tag": 4051, "value": "jax.numpy.ndarray.at" }, { "__type": "Text", "__tag": 4046, "value": " for all writeable backends (those that support " }, { "__type": "InlineCode", "__tag": 4051, "value": "__setitem__" }, { "__type": "Text", "__tag": 4046, "value": ") and routes to the " }, { "__type": "InlineCode", "__tag": 4051, "value": ".at[]" }, { "__type": "Text", "__tag": 4046, "value": " method for JAX arrays." } ] } ], "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/_lib/array_api_extra/_lib/_at.py", "item_line": 61, "item_type": "class", "aliases": [ "scipy.differentiate.xpx.at" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "Given either of these equivalent expressions::\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import array_api_extra as xpx\nx = xpx.at(x)[1].add(2)\nx = xpx.at(x, 1).add(2)\n", "execution_status": "unexpected_exception" }, { "__type": "Text", "__tag": 4046, "value": "\nIf x is a JAX array, they are the same as::\n\n" }, { "__type": "Code", "__tag": 4050, "value": "x = x.at[1].add(2)\n", "execution_status": "unexpected_exception" }, { "__type": "Text", "__tag": 4046, "value": "\nIf x is a read-only NumPy array, they are the same as::\n\n" }, { "__type": "Code", "__tag": 4050, "value": "x = x.copy()\nx[1] += 2\n", "execution_status": "unexpected_exception" }, { "__type": "Text", "__tag": 4046, "value": "\nFor other known backends, they are the same as::\n\n" }, { "__type": "Code", "__tag": 4050, "value": "x[1] += 2\n", "execution_status": "unexpected_exception" } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "jax.numpy.ndarray.at", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "jax.numpy.ndarray.at" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent array method in JAX." } ] } ], "type": null } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "x", "annotation": "Array", "kind": "POSITIONAL_ONLY", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "idx", "annotation": "SetIndex | Undef", "kind": "POSITIONAL_ONLY", "default": "Undef.UNDEF" } ], "return_annotation": "None", "target_name": "at" }, "references": null, "qa": "scipy._lib.array_api_extra._lib._at:at", "arbitrary": [], "local_refs": [ "copy", "idx", "x", "xp" ] }