# Function

`Function(self, *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`
`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
is_Function bool(x) -> bool
space_order The space order.

## 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`