Function

class devito.types.Function(*args)[source]

Bases: DiscreteFunction

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 (str) – Name of the symbol.

  • grid (Grid, optional) – 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.

  • space_order (int or 3-tuple of ints, optional) – Discretisation order for space derivatives. Defaults to 1. 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.

  • shape (tuple of ints, optional) – Shape of the domain region in grid points. Only necessary if grid isn’t given.

  • dimensions (tuple of Dimension, optional) – Dimensions associated with the object. Only necessary if grid isn’t given.

  • dtype (data-type, optional) – Any object that can be interpreted as a numpy data type. Defaults to np.float32.

  • staggered (Dimension or tuple of Dimension or Stagger, optional) – Define how the Function is staggered.

  • 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.

  • padding (int or tuple of ints, optional) –

    Deprecated since version shouldn’t: be used; padding is now automatically inserted.

    Allocate extra grid points to maximize data access alignment. When a tuple of ints, one int per Dimension should be provided.

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.

avg(p=None, dims=None)[source]

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

Parameters:

  • p (int, optional) – The number of summands. Defaults to the halo size.

  • dims (tuple of Dimension, optional) – The Dimensions along which the average is computed. Defaults to self’s spatial dimensions.

property data

The domain data values, as a numpy.ndarray.

Elements are stored in row-major format.

Notes

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.

property data_domain

The domain data values.

Elements are stored in row-major format.

Notes

Alias to self.data.

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.

property data_ro_domain

Read-only view of the domain data values.

property data_ro_with_halo

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

property data_with_halo

The domain+outhalo data values.

Elements are stored in row-major format.

Notes

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.

property dimensions

Tuple of Dimensions representing the object indices.

property dtype

The data type of the object in the generated code, represented as a Python class:

  • numpy.dtype: basic data types. For example, np.float64 -> double.

  • ctypes: composite objects (e.g., structs), foreign types.

property grid

The Grid on which the discretization occurred.

property name

The name of the object.

shape

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

Notes

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

shape_allocated

Shape of the allocated data. It includes the domain and inhalo regions, as well as any additional padding surrounding the halo.

Notes

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

shape_global

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

Notes

In an MPI context, this is the global domain region shape, which is therefore identical on all MPI ranks.

Issues

shape_with_halo

Shape of the domain+outhalo region. The outhalo is the region surrounding the domain that may be read by an Operator.

Notes

In an MPI context, this is the local with_halo region shape. Further, note that the outhalo of inner ranks is typically empty, while the outhalo of boundary ranks contains a number of elements depending on the rank position in the decomposed grid (corner, side, …).

space_dimensions

Tuple of Dimensions defining the physical space.

property space_order

The space order.

sum(p=None, dims=None)[source]

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

Parameters:

  • p (int, optional) – The number of summands. Defaults to the halo size.

  • dims (tuple of Dimension, optional) – The Dimensions along which the sum is computed. Defaults to self’s spatial dimensions.