4.1.4. pde.fields.tensorial module

Defines a tensorial field of rank 2 over a grid

class Tensor2Field(grid: GridBase, data: Optional[Union[int, float, complex, numpy.ndarray, Sequence[NumberOrArray], Sequence[Sequence[Any]], str]] = 'zeros', *, label: str = None, dtype=None, with_ghost_cells: bool = False)[source]

Bases: pde.fields.base.DataFieldBase

Tensor field of rank 2 discretized on a grid

Parameters
  • grid (GridBase) – Grid defining the space on which this field is defined.

  • data (Number or ndarray, optional) – Field values at the support points of the grid. The flag with_ghost_cells determines whether this data array contains values for the ghost cells, too. The resulting field will contain real data unless the data argument contains complex values. Special values are “zeros” or None, initializing the field with zeros, and “empty”, just allocating memory with unspecified values.

  • label (str, optional) – Name of the field

  • dtype (numpy dtype) – The data type of the field. All the numpy dtypes are supported. If omitted, it will be determined from data automatically.

  • with_ghost_cells (bool) – Indicates whether the ghost cells are included in data

divergence(bc: Optional[BoundariesData], out: Optional[VectorField] = None, **kwargs) VectorField[source]

apply tensor divergence and return result as a field

The tensor divergence is a vector field \(v_\alpha\) resulting from a contracting of the derivative of the tensor field \(t_{\alpha\beta}\):

\[v_\alpha = \sum_\beta \frac{\partial t_{\alpha\beta}}{\partial x_\beta}\]
Parameters
  • bc – The boundary conditions applied to the field. Boundary conditions are generally given as a list with one condition for each axis. For periodic axis, only periodic boundary conditions are allowed (indicated by ‘periodic’ and ‘anti-periodic’). For non-periodic axes, different boundary conditions can be specified for the lower and upper end (using a tuple of two conditions). For instance, Dirichlet conditions enforcing a value NUM (specified by {‘value’: NUM}) and Neumann conditions enforcing the value DERIV for the derivative in the normal direction (specified by {‘derivative’: DERIV}) are supported. Note that the special value ‘natural’ imposes periodic boundary conditions for periodic axis and a vanishing derivative otherwise. More information can be found in the boundaries documentation. If the special value None is given, no boundary conditions are enforced. The user then needs to ensure that the ghost cells are set accordingly.

  • out (VectorField, optional) – Optional scalar field to which the result is written.

  • label (str, optional) – Name of the returned field

Returns

result of applying the operator

Return type

VectorField

dot(other: Union[VectorField, Tensor2Field], out: Optional[Union[VectorField, Tensor2Field]] = None, *, conjugate: bool = True, label: str = 'dot product') Union[VectorField, Tensor2Field][source]

calculate the dot product involving a tensor field

This supports the dot product between two tensor fields as well as the product between a tensor and a vector. The resulting fields will be a tensor or vector, respectively.

Parameters
  • other (VectorField or Tensor2Field) – the second field

  • out (VectorField or Tensor2Field, optional) – Optional field to which the result is written.

  • conjugate (bool) – Whether to use the complex conjugate for the second operand

  • label (str, optional) – Name of the returned field

Returns

VectorField or Tensor2Field: result of applying the dot operator

classmethod from_expression(grid: GridBase, expressions: Sequence[Sequence[str]], *, label: str = None, dtype=None) Tensor2Field[source]

create a tensor field on a grid from given expressions

Warning

This implementation uses exec() and should therefore not be used in a context where malicious input could occur.

Parameters
  • grid (GridBase) – Grid defining the space on which this field is defined

  • expressions (list of str) – A 2d list of mathematical expression, one for each component of the tensor field. The expressions determine the values as a function of the position on the grid. The expressions may contain standard mathematical functions and they may depend on the axes labels of the grid. More information can be found in the expression documentation.

  • label (str, optional) – Name of the field

  • dtype (numpy dtype) – The data type of the field. All the numpy dtypes are supported. If omitted, it will be determined from data automatically.

property integral: numpy.ndarray

integral of each component over space

Type

ndarray

make_dot_operator(backend: str = 'numba', *, conjugate: bool = True) Callable[[numpy.ndarray, numpy.ndarray, numpy.ndarray], numpy.ndarray][source]

return operator calculating the dot product involving vector fields

This supports both products between two vectors as well as products between a vector and a tensor.

Warning

This function does not check types or dimensions.

Parameters

conjugate (bool) – Whether to use the complex conjugate for the second operand

Returns

function that takes two instance of ndarray, which contain the discretized data of the two operands. An optional third argument can specify the output array to which the result is written. Note that the returned function is jitted with numba for speed.

plot_components(kind: str = 'auto', *args, title: str = None, constrained_layout: bool = True, filename: str = None, action: str = 'auto', fig_style: dict = None, fig=None, **kwargs) List[List[PlotReference]][source]

visualize all the components of this tensor field

Parameters
  • kind (str or list of str) – Determines the kind of the visualizations. Supported values are image or line. Alternatively, auto determines the best visualization based on the grid.

  • title (str) – Title of the plot. If omitted, the title might be chosen automatically. This is shown above all panels.

  • constrained_layout (bool) – Whether to use constrained_layout in matplotlib.pyplot.figure() call to create a figure. This affects the layout of all plot elements. Generally, spacing might be better with this flag enabled, but it can also lead to problems when plotting multiple plots successively, e.g., when creating a movie.

  • filename (str, optional) – If given, the figure is written to the specified file.

  • action (str) – Decides what to do with the final figure. If the argument is set to show, matplotlib.pyplot.show() will be called to show the plot. If the value is none, the figure will be created, but not necessarily shown. The value close closes the figure, after saving it to a file when filename is given. The default value auto implies that the plot is shown if it is not a nested plot call.

  • fig_style (dict) – Dictionary with properties that will be changed on the figure after the plot has been drawn by calling matplotlib.pyplot.setp(). For instance, using fig_style={‘dpi’: 200} increases the resolution of the figure.

  • fig (matplotlib.figures.Figure) – Figure that is used for plotting. If omitted, a new figure is created.

  • **kwargs – All additional keyword arguments are forwarded to the actual plotting function of all subplots.

Returns

Instances that contain information to update all the plots with new data later.

Return type

2d list of PlotReference

rank: int = 2
symmetrize(make_traceless: bool = False, inplace: bool = False) Tensor2Field[source]

symmetrize the tensor field in place

Parameters
  • make_traceless (bool) – Determines whether the result is also traceless

  • inplace (bool) – Flag determining whether to symmetrize the current field or return a new one

Returns

result of the operation

Return type

Tensor2Field

to_scalar(scalar: str = 'auto', *, label: str = 'scalar `{scalar}`') ScalarField[source]

return a scalar field by applying method

The invariants of the tensor field \(\boldsymbol{A}\) are

\[\begin{split}I_1 &= \mathrm{tr}(\boldsymbol{A}) \\ I_2 &= \frac12 \left[ (\mathrm{tr}(\boldsymbol{A})^2 - \mathrm{tr}(\boldsymbol{A}^2) \right] \\ I_3 &= \det(A)\end{split}\]

where tr denotes the trace and det denotes the determinant. Note that the three invariants can only be distinct and non-zero in three dimensions. In two dimensional spaces, we have the identity \(2 I_2 = I_3\) and in one-dimensional spaces, we have \(I_1 = I_3\) as well as \(I_2 = 0\).

Parameters
  • scalar (str) – The method to calculate the scalar. Possible choices include norm (the default chosen when the value is auto), min, max, squared_sum, norm_squared, trace (or invariant1), invariant2, and determinant (or invariant3)

  • label (str, optional) – Name of the returned field

Returns

the scalar field after applying the operation

Return type

ScalarField

trace(label: str = 'trace') ScalarField[source]

return the trace of the tensor field as a scalar field

Parameters

label (str, optional) – Name of the returned field

Returns

scalar field of traces

Return type

ScalarField

transpose(label: str = 'transpose') Tensor2Field[source]

return the transpose of the tensor field

Parameters

label (str, optional) – Name of the returned field

Returns

transpose of the tensor field

Return type

Tensor2Field