class devito.types.SparseFunction(*args, **kwargs)[source]

Bases: devito.types.sparse.AbstractSparseFunction

Tensor symbol representing a sparse array in symbolic equations.

A SparseFunction carries multi-dimensional data that are not aligned with the computational grid. As such, each data value is associated some coordinates. A SparseFunction provides symbolic interpolation routines to convert between Functions and sparse data points. These are based upon standard [bi,tri]linear interpolation.

  • name (str) – Name of the symbol.
  • npoint (int) – Number of sparse points.
  • grid (Grid) – The computational domain from which the sparse points are sampled.
  • coordinates (np.ndarray, optional) – The coordinates of each sparse point.
  • space_order (int, optional) – Discretisation order for space derivatives. Defaults to 0.
  • shape (tuple of ints, optional) – Shape of the object. Defaults to (npoint,).
  • dimensions (tuple of Dimension, optional) – Dimensions associated with the object. Only necessary if the SparseFunction defines a multi-dimensional tensor.
  • dtype (data-type, optional) – Any object that can be interpreted as a numpy data type. Defaults to np.float32.
  • initializer (callable or any object exposing the buffer interface, optional) – Data initializer. If a callable is provided, data is allocated lazily.
  • allocator (MemoryAllocator, optional) – 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.



>>> from devito import Grid, SparseFunction
>>> grid = Grid(shape=(4, 4))
>>> sf = SparseFunction(name='sf', grid=grid, npoint=2)
>>> sf


Data([0., 0.], dtype=float32)
>>> sf.coordinates
sf_coords(p_sf, d)
>>> sf.coordinates_data
array([[0., 0.],
       [0., 0.]], dtype=float32)

Symbolic interpolation routines

>>> from devito import Function
>>> f = Function(name='f', grid=grid)
>>> exprs0 = sf.interpolate(f)
>>> exprs1 = sf.inject(f, sf)


The parameters must always be given as keyword arguments, since SymPy uses *args to (re-)create the dimension arguments of the symbolic object. About SparseFunction and MPI. There is a clear difference between:

  • Where the sparse points physically live, i.e., on which MPI rank. This depends on the user code, particularly on how the data is set up.
  • and which MPI rank logically owns a given sparse point. The logical ownership depends on where the sparse point is located within self.grid.

Right before running an Operator (i.e., upon a call to op.apply), a SparseFunction “scatters” its physically owned sparse points so that each MPI rank gets temporary access to all of its logically owned sparse points. A “gather” operation, executed before returning control to user-land, updates the physically owned sparse points in by collecting the values computed during op.apply from different MPI ranks.


The domain data values, as a numpy.ndarray.

Elements are stored in row-major format.


With this accessor you are claiming that you will modify the values you get back. If you only need to look at the values, use data_ro() instead.


The domain data values.

Elements are stored in row-major format.


Alias to

With this accessor you are claiming that you will modify the values you get back. If you only need to look at the values, use data_ro_domain() instead.


Read-only view of the domain data values.


Read-only view of the domain+outhalo data values.


The domain+outhalo data values.

Elements are stored in row-major format.


With this accessor you are claiming that you will modify the values you get back. If you only need to look at the values, use data_ro_with_halo() instead.


Tuple of Dimensions representing the object indices.


The data type of the object.


The Grid on which the discretization occurred.


The reference grid point corresponding to each sparse point.


When using MPI, this property refers to the physically owned sparse points.

guard(expr=None, offset=0)[source]

Generate guarded expressions, that is expressions that are evaluated by an Operator only if certain conditions are met. The introduced condition, here, is that all grid points in the support of a sparse value must fall within the grid domain (i.e., not on the halo).

  • expr (expr-like, optional) – Input expression, from which the guarded expression is derived. If not specified, defaults to self.
  • offset (int, optional) – Relax the guard condition by introducing a tolerance offset.
inject(field, expr, offset=0)[source]

Generate equations injecting an arbitrary expression into a field.

  • field (Function) – Input field into which the injection is performed.
  • expr (expr-like) – Injected expression.
  • offset (int, optional) – Additional offset from the boundary.
interpolate(expr, offset=0, increment=False, self_subs={})[source]

Generate equations interpolating an arbitrary expression into self.

  • expr (expr-like) – Input expression to interpolate.
  • offset (int, optional) – Additional offset from the boundary.
  • increment (bool, optional) – If True, generate increments (Inc) rather than assignments (Eq).

The name of the object.


Shape of the domain region. The domain constitutes the area of the data written to by an Operator.


In an MPI context, this is the local domain region shape.


The space order.