# 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
+ g(x, y), x) Derivative(f(x, y)
```

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
/h_x - f(x - h_x, y)/h_x
f(x, y)>>> f.dxr
Derivative(f(x, y), x)
```

Second-order derivative through centered finite-difference approximation

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

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

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