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	devito.data - type	Any object that can be interpreted as a numpy data type.	np.float32
save	int or devito.types.utils.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	devito.types.dimension.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
time_order	The time order.