# TimeFunction

``TimeFunction(self, *args, **kwargs)``

Tensor symbol representing a discrete function in symbolic equations.

A TimeFunction carries multi-dimensional data and provides operations to create finite-differences approximations, in both space and time.

A TimeFunction encapsulates space- and time-varying data.

## 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`
time_order int Discretization order for time derivatives. Defaults to 1. 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`
save int or Buffer By default, `save=None`, which indicates the use of alternating buffers. This enables cyclic writes to the TimeFunction. For example, if the TimeFunction `u(t, x)` has shape (3, 100), then, in an Operator, `t` will assume the values `1, 2, 0, 1, 2, 0, 1, ...` (note that the very first value depends on the stencil equation in which `u` is written.). The default size of the time buffer when `save=None` is `time_order + 1`. To specify a different size for the time buffer, one should use the syntax `save=Buffer(mysize)`. Alternatively, if all of the intermediate results are required (or, simply, to avoid using an alternating buffer), an explicit value for `save` ( an integer) must be provided. `None`
time_dim Dimension TimeDimension to be used in the TimeFunction. `grid.time_dim`
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, TimeFunction
>>> grid = Grid(shape=(4, 4))
>>> f = TimeFunction(name='f', grid=grid)
>>> f
f(t, x, y)
>>> g = TimeFunction(name='g', grid=grid, time_order=2)
>>> g
g(t, x, y)``````

First-order derivatives through centered finite-difference approximations

``````>>> f.dx
Derivative(f(t, x, y), x)
>>> f.dt
Derivative(f(t, x, y), t)
>>> g.dt
Derivative(g(t, x, y), t)``````

When using the alternating buffer protocol, the size of the time dimension is given by `time_order + 1`

``````>>> f.shape
(2, 4, 4)
>>> g.shape
(3, 4, 4)``````

One can drop the alternating buffer protocol specifying a value for `save`

``````>>> h = TimeFunction(name='h', grid=grid, save=20)
>>> h
h(time, x, y)
>>> h.shape
(20, 4, 4)``````

## Notes

The parameters must always be given as keyword arguments, since SymPy uses `*args` to (re-)create the dimension arguments of the symbolic object. If the parameter `grid` is provided, the values for `shape`, `dimensions` and `dtype` will be derived from it. When present, the parameter `shape` should only define the spatial shape of the grid. The temporal dimension will be inserted automatically as the leading dimension.

## Attributes

Name Description
backward Symbol for the time-backward state of the TimeFunction.
forward Symbol for the time-forward state of the TimeFunction.
is_TimeDependent bool(x) -> bool
is_TimeFunction bool(x) -> bool
layer The memory hierarchy layer in which the TimeFunction is stored.
time_order The time order.
Back to top