# Finite-difference approximations¶

`devito.finite_differences.finite_difference.``first_derivative`(expr, dim, fd_order=None, side=centered[0], matvec=direct[1], symbolic=False)[source]

First-order derivative of a given expression.

Parameters
• expr (expr-like) – Expression for which the first-order derivative is produced.

• dim (Dimension) – The Dimension w.r.t. which to differentiate.

• fd_order (int, optional) – Coefficient discretization order. Note: this impacts the width of the resulting stencil. Defaults to `expr.space_order`

• side (Side, optional) – Side of the finite difference location, centered (at x), left (at x - 1) or right (at x +1). Defaults to `centered`.

• matvec (Transpose, optional) – Forward (matvec=direct) or transpose (matvec=transpose) mode of the finite difference. Defaults to `direct`.

Returns

First-order derivative of `expr`.

Return type

expr-like

Examples

```>>> from devito import Function, Grid, first_derivative, transpose
>>> grid = Grid(shape=(4, 4))
>>> x, _ = grid.dimensions
>>> f = Function(name='f', grid=grid)
>>> g = Function(name='g', grid=grid)
>>> first_derivative(f*g, dim=x)
-f(x, y)*g(x, y)/h_x + f(x + h_x, y)*g(x + h_x, y)/h_x
```

Semantically, this is equivalent to

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

The only difference is that in the latter case derivatives remain unevaluated. The expanded form is obtained via `evaluate`

```>>> (f*g).dx.evaluate
-f(x, y)*g(x, y)/h_x + f(x + h_x, y)*g(x + h_x, y)/h_x
```

For the adjoint mode of the first derivative, pass `matvec=transpose`

```>>> g = Function(name='g', grid=grid)
>>> first_derivative(f*g, dim=x, matvec=transpose)
f(x, y)*g(x, y)/h_x - f(x + h_x, y)*g(x + h_x, y)/h_x
```

This is also accessible via the .T shortcut

```>>> (f*g).dx.T.evaluate
f(x, y)*g(x, y)/h_x - f(x + h_x, y)*g(x + h_x, y)/h_x
```
`devito.finite_differences.finite_difference.``second_derivative`(expr, dim, fd_order, stagger=None, **kwargs)[source]

Second-order derivative of a given expression.

Parameters
• expr (expr-like) – Expression for which the derivative is produced.

• dim (Dimension) – The Dimension w.r.t. which to differentiate.

• fd_order (int) – Coefficient discretization order. Note: this impacts the width of the resulting stencil.

• stagger (Side, optional) – Shift of the finite-difference approximation.

Returns

Second-order derivative of `expr`.

Return type

expr-like

Examples

```>>> from devito import Function, Grid, second_derivative
>>> grid = Grid(shape=(4, 4))
>>> x, _ = grid.dimensions
>>> f = Function(name='f', grid=grid, space_order=2)
>>> g = Function(name='g', grid=grid, space_order=2)
>>> second_derivative(f*g, dim=x, fd_order=2)
-2.0*f(x, y)*g(x, y)/h_x**2 + f(x - h_x, y)*g(x - h_x, y)/h_x**2 + f(x + h_x, y)*g(x + h_x, y)/h_x**2
```

Semantically, this is equivalent to

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

The only difference is that in the latter case derivatives remain unevaluated. The expanded form is obtained via `evaluate`

```>>> (f*g).dx2.evaluate
-2.0*f(x, y)*g(x, y)/h_x**2 + f(x - h_x, y)*g(x - h_x, y)/h_x**2 + f(x + h_x, y)*g(x + h_x, y)/h_x**2
```
`devito.finite_differences.finite_difference.``cross_derivative`(expr, dims, fd_order, deriv_order, stagger=None, **kwargs)[source]

Arbitrary-order cross derivative of a given expression.

Parameters
• expr (expr-like) – Expression for which the cross derivative is produced.

• dims (tuple of Dimension) – Dimensions w.r.t. which to differentiate.

• fd_order (tuple of ints) – Coefficient discretization order. Note: this impacts the width of the resulting stencil.

• deriv_order (tuple of ints) – Derivative order, e.g. 2 for a second-order derivative.

• stagger (tuple of Side, optional) – Shift of the finite-difference approximation.

Returns

Cross-derivative of `expr`.

Return type

expr-like

Examples

```>>> from devito import Function, Grid, second_derivative
>>> grid = Grid(shape=(4, 4))
>>> x, y = grid.dimensions
>>> f = Function(name='f', grid=grid, space_order=2)
>>> g = Function(name='g', grid=grid, space_order=2)
>>> cross_derivative(f*g, dims=(x, y), fd_order=(2, 2), deriv_order=(1, 1))
-0.5*(-0.5*f(x - h_x, y - h_y)*g(x - h_x, y - h_y)/h_x + 0.5*f(x + h_x, y - h_y)*g(x + h_x, y - h_y)/h_x)/h_y + 0.5*(-0.5*f(x - h_x, y + h_y)*g(x - h_x, y + h_y)/h_x + 0.5*f(x + h_x, y + h_y)*g(x + h_x, y + h_y)/h_x)/h_y
```

Semantically, this is equivalent to

```>>> (f*g).dxdy
Derivative(f(x, y)*g(x, y), x, y)
```

The only difference is that in the latter case derivatives remain unevaluated. The expanded form is obtained via `evaluate`

```>>> (f*g).dxdy.evaluate
-0.5*(-0.5*f(x - h_x, y - h_y)*g(x - h_x, y - h_y)/h_x + 0.5*f(x + h_x, y - h_y)*g(x + h_x, y - h_y)/h_x)/h_y + 0.5*(-0.5*f(x - h_x, y + h_y)*g(x - h_x, y + h_y)/h_x + 0.5*f(x + h_x, y + h_y)*g(x + h_x, y + h_y)/h_x)/h_y
```
`devito.finite_differences.finite_difference.``generic_derivative`(expr, dim, fd_order, deriv_order, stagger=None, symbolic=False, matvec=direct[1])[source]

Arbitrary-order derivative of a given expression.

Parameters
• expr (expr-like) – Expression for which the derivative is produced.

• dim (Dimension) – The Dimension w.r.t. which to differentiate.

• fd_order (int) – Coefficient discretization order. Note: this impacts the width of the resulting stencil.

• deriv_order (int) – Derivative order, e.g. 2 for a second-order derivative.

• stagger (Side, optional) – Shift of the finite-difference approximation.

Returns

`deriv-order` derivative of `expr`.

Return type

expr-like