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