4.1.6 pde.fields.vectorial module

Defines a vectorial field over a grid.

class VectorField(grid, data='zeros', *, label=None, dtype=None, with_ghost_cells=False)[source]

Bases: DataFieldBase

Vector field discretized on a grid.

Warning

Components of the vector field are given in the local basis. While the local basis is identical to the global basis in Cartesian coordinates, the local basis depends on position in curvilinear coordinate systems. Moreover, the field always contains all components, even if the underlying grid assumes symmetries.

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. If omitted, it will be determined from data automatically.

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

divergence(bc, out=None, **kwargs)[source]

Apply divergence operator and return result as a field.

Parameters:

  • bc (BoundariesData | None) – The boundary conditions applied to the field. Boundary conditions are generally given as a list with one condition for each axis. For periodic axes, 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 (ScalarField, optional) – Optional scalar field to which the result is written.

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

  • **kwargs – Additional arguments affecting how the operator behaves.

Returns:

Divergence of the field

Return type:

ScalarField

dot(other, out=None, *, conjugate=True, label='dot product')[source]

Calculate the dot product involving a vector field.

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

Parameters:

  • other (VectorField or Tensor2Field) – the second field

  • out (ScalarField or VectorField, 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:

ScalarField or VectorField: result of applying the operator

Return type:

ScalarField | VectorField

classmethod from_expression(grid, expressions, *, user_funcs=None, consts=None, label=None, dtype=None)[source]

Create a vector 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 list of mathematical expression, one for each component of the vector 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.

  • user_funcs (dict, optional) – A dictionary with user defined functions that can be used in the expression

  • consts (dict, optional) – A dictionary with user defined constants that can be used in the expression. The values of these constants should either be numbers or ndarray.

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

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

Return type:

VectorField

classmethod from_scalars(fields, *, label=None, dtype=None)[source]

Create a vector field from a list of ScalarFields.

Note that the data of the scalar fields is copied in the process

Parameters:

  • fields (list) – The list of (compatible) scalar fields

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

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

Returns:

the resulting vector field

Return type:

VectorField

get_vector_data(transpose=False, max_points=None, **kwargs)[source]

Return data for a vector plot of the field.

Parameters:

  • transpose (bool) – Determines whether the transpose of the data should be plotted.

  • max_points (int) – The maximal number of points that is used along each axis. This option can be used to sub-sample the data.

  • **kwargs – Additional parameters forwarded to grid.get_image_data

Returns:

Information useful for plotting an vector field

Return type:

dict

gradient(bc, out=None, **kwargs)[source]

Apply vector gradient operator and return result as a field.

The vector gradient field is a tensor field \(t_{\alpha\beta}\) that specifies the derivatives of the vector field \(v_\alpha\) with respect to all coordinates \(x_\beta\).

Parameters:

  • bc (BoundariesData | None) – The boundary conditions applied to the field. Boundary conditions need to determine all components of the vector field. Boundary conditions are generally given as a list with one condition for each axis. For periodic axes, 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 vector field to which the result is written.

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

  • **kwargs – Additional arguments affecting how the operator behaves.

Returns:

Gradient of the field

Return type:

Tensor2Field

property integral: ndarray

integral of each component over space.

Type:

ndarray

interpolate_to_grid(grid, *, bc=None, fill=None, label=None)[source]

Interpolate the data of this vector field to another grid.

Parameters:

  • grid (GridBase) – The grid of the new field onto which the current field is interpolated.

  • bc (BoundariesData | None) – The boundary conditions applied to the field, which affects values close to the boundary. If omitted, the argument fill is used to determine values outside the domain. Boundary conditions are generally given as a list with one condition for each axis. For periodic axes, 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.

  • fill (Number, optional) – Determines how values out of bounds are handled. If None, a ValueError is raised when out-of-bounds points are requested. Otherwise, the given value is returned.

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

  • self (VectorField)

Returns:

Field of the same rank as the current one.

Return type:

VectorField

laplace(bc, out=None, **kwargs)[source]

Apply vector Laplace operator and return result as a field.

The vector Laplacian is a vector field \(L_\alpha\) containing the second derivatives of the vector field \(v_\alpha\) with respect to the coordinates \(x_\beta\):

\[L_\alpha = \sum_\beta \frac{\partial^2 v_\alpha}{\partial x_\beta \partial x_\beta}\]
Parameters:

  • bc (BoundariesData | None) – The boundary conditions applied to the field. Boundary conditions are generally given as a list with one condition for each axis. For periodic axes, 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 vector field to which the result is written.

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

  • **kwargs – Additional arguments affecting how the operator behaves.

Returns:

Laplacian of the field

Return type:

VectorField

make_outer_prod_operator(backend='numba')[source]

Return operator calculating the outer product of two vector fields.

Warning

This function does not check types or dimensions.

Parameters:

backend (str) – The backend (e.g., ‘numba’ or ‘scipy’) used for this operator.

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.

Return type:

Callable[[ndarray, ndarray, ndarray | None], ndarray]

outer_product(other, out=None, *, label=None)[source]

Calculate the outer product of this vector field with another.

Parameters:

  • other (VectorField) – The second vector field

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

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

Returns:

result of the operation

Return type:

Tensor2Field

rank: int = 1
to_scalar(scalar='auto', *, label='scalar `{scalar}`')[source]

Return scalar variant of the field.

Parameters:

  • scalar (str) – Choose the method to use. Possible choices are norm, max, min, squared_sum, norm_squared, or an integer specifying which component is returned (indexing starts at 0). The default value auto picks the method automatically: The first (and only) component is returned for real fields on one-dimensional spaces, while the norm of the vector is returned otherwise.

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

Returns:

The scalar field after applying the operation

Return type:

pde.fields.scalar.ScalarField