Function

Function(*args, **kwargs)

Tensor symbol representing a discrete function in symbolic equations.

A Function carries multi-dimensional data and provides operations to create finite-differences approximations.

A Function encapsulates space-varying data; for data that also varies in time, use TimeFunction instead.

Parameters

Name Type Description Default
name str Name of the symbol. required
grid Grid Carries shape, dimensions, and dtype of the Function. When grid is not provided, shape and dimensions must be given. For MPI execution, a Grid is compulsory. required
space_order int or 3-tuple of ints Discretisation order for space derivatives. space_order also impacts the number of points available around a generic point of interest. By default, space_order points are available on both sides of a generic point of interest, including those nearby the grid boundary. Sometimes, fewer points suffice; in other scenarios, more points are necessary. In such cases, instead of an integer, one can pass: * a 3-tuple (o, lp, rp) indicating the discretization order (o) as well as the number of points on the left (lp) and right (rp) sides of a generic point of interest; * a 2-tuple (o, ((lp0, rp0), (lp1, rp1), ...)) indicating the discretization order (o) as well as the number of points on the left/right sides of a generic point of interest for each SpaceDimension. 1
interp_order Order of the interpolation scheme used to evaluate the Function at non-grid points (e.g., when using a Function as a parameter to be evaluated at a staggered location). required
shape tuple of ints Shape of the domain region in grid points. Only necessary if grid isn’t given. required
dimensions tuple of Dimension Dimensions associated with the object. Only necessary if grid isn’t given. required
dtype data - type Any object that can be interpreted as a numpy data type. np.float32
staggered Dimension or tuple of Dimension or Stagger Define how the Function is staggered. None
initializer callable or any object exposing the buffer interface Data initializer. If a callable is provided, data is allocated lazily. None
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
padding int or tuple of ints Allocate extra grid points to maximize data access alignment. When a tuple of ints, one int per Dimension should be provided. required

Examples

Creation

>>> from devito import Grid, Function
>>> grid = Grid(shape=(4, 4))
>>> f = Function(name='f', grid=grid)
>>> f
f(x, y)
>>> g = Function(name='g', grid=grid, space_order=2)
>>> g
g(x, y)

First-order derivatives through centered finite-difference approximations

>>> f.dx
Derivative(f(x, y), x)
>>> f.dy
Derivative(f(x, y), y)
>>> g.dx
Derivative(g(x, y), x)
>>> (f + g).dx
Derivative(f(x, y) + g(x, y), x)

First-order derivatives through left/right finite-difference approximations

>>> f.dxl
Derivative(f(x, y), x)

Note that the fact that it’s a left-derivative isn’t captured in the representation. However, upon derivative expansion, this becomes clear

>>> f.dxl.evaluate
f(x, y)/h_x - f(x - h_x, y)/h_x
>>> f.dxr
Derivative(f(x, y), x)

Second-order derivative through centered finite-difference approximation

>>> g.dx2
Derivative(g(x, y), (x, 2))

Notes

The parameters must always be given as keyword arguments, since SymPy uses *args to (re-)create the dimension arguments of the symbolic object.

Attributes

Name Description
interp_order The interpolation order.
is_Function bool(x) -> bool
is_autopaddable bool(x) -> bool
space_order The space order.
staggered The staggered indices of the object.

Methods

Name Description
avg Generate a symbolic expression computing the average of p points
sum Generate a symbolic expression computing the sum of p points

avg

avg(p=None, dims=None)

Generate a symbolic expression computing the average of p points along the spatial dimensions dims.

Parameters

Name Type Description Default
p int The number of summands. Defaults to the halo size. None
dims tuple of Dimension The Dimensions along which the average is computed. Defaults to self’s spatial dimensions. None

sum

sum(p=None, dims=None)

Generate a symbolic expression computing the sum of p points along the spatial dimensions dims.

Parameters

Name Type Description Default
p int The number of summands. Defaults to the halo size. None
dims tuple of Dimension The Dimensions along which the sum is computed. Defaults to self’s spatial dimensions. None
Back to top