{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# \n",
"\n",
"# SparseFunction\n",
"\n",
"``` python\n",
"SparseFunction(self, *args, **kwargs)\n",
"```\n",
"\n",
"Tensor symbol representing a sparse array in symbolic equations.\n",
"\n",
"A SparseFunction carries multi-dimensional data that are not aligned\n",
"with the computational grid. As such, each data value is associated some\n",
"coordinates. A SparseFunction provides symbolic interpolation routines\n",
"to convert between Functions and sparse data points. These are based\n",
"upon standard \\[bi,tri\\]linear interpolation.\n",
"\n",
"## Parameters\n",
"\n",
"| Name | Type | Description | Default |\n",
"|-----|--------------|-------------------------------------------------|-----|\n",
"| name | str | Name of the symbol. | *required* |\n",
"| npoint | int | Number of sparse points. | *required* |\n",
"| grid | Grid | The computational domain from which the sparse points are sampled. | *required* |\n",
"| coordinates | np.ndarray | The coordinates of each sparse point. | *required* |\n",
"| space_order | int | Discretisation order for space derivatives. | `0` |\n",
"| shape | tuple of ints | Shape of the object. | `(npoint,)` |\n",
"| dimensions | tuple of Dimension | Dimensions associated with the object. Only necessary if the SparseFunction defines a multi-dimensional tensor. | *required* |\n",
"| dtype | data - type | Any object that can be interpreted as a numpy data type. | `np.float32` |\n",
"| initializer | callable or any object exposing the buffer interface | Data initializer. If a callable is provided, data is allocated lazily. | `None` |\n",
"| allocator | MemoryAllocator | Controller for memory allocation. To be used, for example, when one wants to take advantage of the memory hierarchy in a NUMA architecture. Refer to `default_allocator.__doc__` for more information. | *required* |\n",
"| interpolation | | The interpolation type to be used by the SparseFunction. Supported types are ‘linear’ and ‘sinc’. | *required* |\n",
"| r | | The radius of the interpolation operators provided by the SparseFunction. | *required* |\n",
"\n",
"## Examples\n",
"\n",
"Creation\n",
"\n",
"``` python\n",
">>> from devito import Grid, SparseFunction\n",
">>> grid = Grid(shape=(4, 4))\n",
">>> sf = SparseFunction(name='sf', grid=grid, npoint=2)\n",
">>> sf\n",
"sf(p_sf)\n",
"```\n",
"\n",
"Inspection\n",
"\n",
"``` python\n",
">>> sf.data\n",
"Data([0., 0.], dtype=float32)\n",
">>> sf.coordinates\n",
"sf_coords(p_sf, d)\n",
">>> sf.coordinates_data\n",
"array([[0., 0.],\n",
" [0., 0.]], dtype=float32)\n",
"```\n",
"\n",
"Symbolic interpolation routines\n",
"\n",
"``` python\n",
">>> from devito import Function\n",
">>> f = Function(name='f', grid=grid)\n",
">>> exprs0 = sf.interpolate(f)\n",
">>> exprs1 = sf.inject(f, sf)\n",
"```\n",
"\n",
"## Notes\n",
"\n",
"The parameters must always be given as keyword arguments, since SymPy\n",
"uses `*args` to (re-)create the Dimension arguments of the symbolic\n",
"object. About SparseFunction and MPI. There is a clear difference\n",
"between:\n",
"\n",
" * Where the sparse points *physically* live, i.e., on which MPI rank. This\n",
" depends on the user code, particularly on how the data is set up.\n",
" * and which MPI rank *logically* owns a given sparse point. The logical\n",
" ownership depends on where the sparse point is located within ``self.grid``.\n",
"\n",
"Right before running an Operator (i.e., upon a call to `op.apply`), a\n",
"SparseFunction “scatters” its physically owned sparse points so that\n",
"each MPI rank gets temporary access to all of its logically owned sparse\n",
"points. A “gather” operation, executed before returning control to\n",
"user-land, updates the physically owned sparse points in `self.data` by\n",
"collecting the values computed during `op.apply` from different MPI\n",
"ranks.\n",
"\n",
"## Attributes\n",
"\n",
"| Name | Description |\n",
"|------------------------------------|------------------------------------|\n",
"| [is_SparseFunction](#devito.SparseFunction.is_SparseFunction) | bool(x) -\\> bool |"
],
"id": "90040310-2008-4375-8c5c-ddedd50f9c10"
}
],
"nbformat": 4,
"nbformat_minor": 5,
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
}
}
}