Built-in Operators

Devito provides a number of convenience Operators that can be imported and run in user code to facilitate development. These are exposed as free functions.

All built-in Operators support MPI.

Built-in Operators provided by Devito.

devito.builtins.assign(f, rhs=0, options=None, name='assign', **kwargs)[source]

Assign a list of RHSs to a list of Functions.

Parameters
  • f (Function or list of Functions) – The left-hand side of the assignment.

  • rhs (expr-like or list of expr-like, optional) – The right-hand side of the assignment.

  • options (dict or list of dict, optional) – Dictionary or list (of len(f)) of dictionaries containing optional arguments to be passed to Eq.

  • name (str, optional) – Name of the operator.

Examples

>>> from devito import Grid, Function, assign
>>> grid = Grid(shape=(4, 4))
>>> f = Function(name='f', grid=grid, dtype=np.int32)
>>> g = Function(name='g', grid=grid, dtype=np.int32)
>>> h = Function(name='h', grid=grid, dtype=np.int32)
>>> functions = [f, g, h]
>>> scalars = [1, 2, 3]
>>> assign(functions, scalars)
>>> f.data
Data([[1, 1, 1, 1],
      [1, 1, 1, 1],
      [1, 1, 1, 1],
      [1, 1, 1, 1]], dtype=int32)
>>> g.data
Data([[2, 2, 2, 2],
      [2, 2, 2, 2],
      [2, 2, 2, 2],
      [2, 2, 2, 2]], dtype=int32)
>>> h.data
Data([[3, 3, 3, 3],
      [3, 3, 3, 3],
      [3, 3, 3, 3],
      [3, 3, 3, 3]], dtype=int32)
devito.builtins.smooth(f, g, axis=None)[source]

Smooth a Function through simple moving average.

Parameters
  • f (Function) – The left-hand side of the smoothing kernel, that is the smoothed Function.

  • g (Function) – The right-hand side of the smoothing kernel, that is the Function being smoothed.

  • axis (Dimension or list of Dimensions, optional) – The Dimension along which the smoothing operation is performed. Defaults to f’s innermost Dimension.

Notes

More info about simple moving average available at:

https://en.wikipedia.org/wiki/Moving_average#Simple_moving_average
devito.builtins.gaussian_smooth(f, sigma=1, truncate=4.0, mode='reflect')[source]

Gaussian smooth function.

Parameters
  • f (Function) – The left-hand side of the smoothing kernel, that is the smoothed Function.

  • sigma (float, optional) – Standard deviation. Default is 1.

  • truncate (float, optional) – Truncate the filter at this many standard deviations. Default is 4.0.

  • mode (str, optional) – The function initialisation mode. ‘constant’ and ‘reflect’ are accepted. Default mode is ‘reflect’.

devito.builtins.initialize_function(function, data, nbl, mapper=None, mode='constant', name='padfunc')[source]

Initialize a Function with the given data. data does not include the nbl outer/boundary layers; these are added via padding by this function.

Parameters
  • function (Function) – The initialised object.

  • data (ndarray or Function) – The data used for initialisation.

  • nbl (int or tuple of int) – Number of outer layers (such as absorbing layers for boundary damping).

  • mapper (dict, optional) – Dictionary containing, for each dimension of function, a sub-dictionary containing the following keys: 1) ‘lhs’: List of additional expressions to be added to the LHS expressions list. 2) ‘rhs’: List of additional expressions to be added to the RHS expressions list. 3) ‘options’: Options pertaining to the additional equations that will be constructed.

  • mode (str, optional) – The function initialisation mode. ‘constant’ and ‘reflect’ are accepted.

  • name (str, optional) – The name assigned to the operator.

Examples

In the following example the ‘interior’ of a function is set to one plus the value on the boundary.

>>> import numpy as np
>>> from devito import Grid, SubDomain, Function, initialize_function

Create the computational domain:

>>> grid = Grid(shape=(6, 6))
>>> x, y = grid.dimensions

Create the Function we wish to set along with the data to set it:

>>> f = Function(name='f', grid=grid, dtype=np.int32)
>>> data = np.full((4, 4), 2, dtype=np.int32)

Now create the additional expressions and options required to set the value of the interior region to one greater than the boundary value. Note that the equation is specified on the second (final) grid dimension so that additional equation is executed after padding is complete.

>>> lhs = f
>>> rhs = f+1
>>> options = {'subdomain': grid.subdomains['interior']}
>>> mapper = {}
>>> mapper[y] = {'lhs': lhs, 'rhs': rhs, 'options': options}

Call the initialize_function routine:

>>> initialize_function(f, data, 1, mapper=mapper)
>>> f.data
Data([[2, 2, 2, 2, 2, 2],
      [2, 3, 3, 3, 3, 2],
      [2, 3, 3, 3, 3, 2],
      [2, 3, 3, 3, 3, 2],
      [2, 3, 3, 3, 3, 2],
      [2, 2, 2, 2, 2, 2]], dtype=int32)
devito.builtins.norm(f, order=2)[source]

Compute the norm of a Function.

Parameters
  • f (Function) – Input Function.

  • order (int, optional) – The order of the norm. Defaults to 2.

devito.builtins.sumall(f)[source]

Compute the sum of all Function data.

Parameters

f (Function) – Input Function.

devito.builtins.inner(f, g)[source]

Inner product of two Functions.

Parameters
Raises

ValueError – If the two input Functions are defined over different grids, or have different dimensionality, or their dimension-wise sizes don’t match. If in input are two SparseFunctions and their coordinates don’t match, the exception is raised.

Notes

The inner product is the sum of all dimension-wise products. For 1D Functions, the inner product corresponds to the dot product.

devito.builtins.mmin(f)[source]

Retrieve the minimum.

Parameters

f (array_like or Function) – Input operand.

devito.builtins.mmax(f)[source]

Retrieve the maximum.

Parameters

f (array_like or Function) – Input operand.