4.1.3 pde.fields.scalar module
Defines a scalar field over a grid
- class ScalarField(grid, data='zeros', *, label=None, dtype=None, with_ghost_cells=False)[source]
Bases:
DataFieldBase
Scalar field 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. If omitted, it will be determined from data automatically.
with_ghost_cells (bool) – Indicates whether the ghost cells are included in data
- classmethod from_expression(grid, expression, *, user_funcs=None, consts=None, label=None, dtype=None)[source]
create a scalar field on a grid from a given expression
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 definedexpression (str) – Mathematical expression for the scalar value as a function of the position on the grid. The expression may contain standard mathematical functions and it 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:
- classmethod from_image(path, bounds=None, periodic=False, *, label=None)[source]
create a scalar field from an image
- Parameters:
path (
Path
or str) – The path to the image filebounds (tuple, optional) – Gives the coordinate range for each axis. This should be two tuples of two numbers each, which mark the lower and upper bound for each axis.
periodic (bool or list) – Specifies which axes possess periodic boundary conditions. This is either a list of booleans defining periodicity for each individual axis or a single boolean value specifying the same periodicity for all axes.
label (str, optional) – Name of the field
- Return type:
- get_boundary_field(index, bc=None, *, label=None)[source]
get the field on the specified boundary
- Parameters:
index (str or tuple) – Index specifying the boundary. Can be either a string given in
boundary_names
, like"left"
, or a tuple of the axis index perpendicular to the boundary and a boolean specifying whether the boundary is at the upper side of the axis or not, e.g.,(1, True)
.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.
label (str) – Label of the returned field
- Returns:
The field on the boundary
- Return type:
- gradient(bc, out=None, **kwargs)[source]
apply gradient 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 (VectorField, optional) – Optional vector field to which the result is written.
label (str, optional) – Name of the returned field
- Returns:
result of applying the operator
- Return type:
- gradient_squared(bc, out=None, **kwargs)[source]
apply squared gradient operator and return result as a field
This evaluates \(|\nabla \phi|^2\) for the scalar field \(\phi\)
- 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 vector field to which the result is written.
label (str, optional) – Name of the returned field
central (bool) – Determines whether a central difference approximation is used for the gradient operator or not. If not, the squared gradient is calculated as the mean of the squared values of the forward and backward derivatives, which thus includes the value at a support point in the result at the same point.
- Returns:
the squared gradient of the field
- Return type:
- interpolate_to_grid(grid, *, bc=None, fill=None, label=None)[source]
interpolate the data of this scalar 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 (ScalarField) –
- Returns:
Field of the same rank as the current one.
- Return type:
- laplace(bc, out=None, **kwargs)[source]
apply Laplace 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
backend (str) – The backend (e.g., ‘numba’ or ‘scipy’) used for this operator.
- Returns:
the Laplacian of the field
- Return type:
- project(axes, method='integral', label=None)[source]
project scalar field along given axes
- Parameters:
axes (list of str) – The names of the axes that are removed by the projection operation. The valid names for a given grid are the ones in the
GridBase.axes
attribute.method (str) – The projection method. This can be either ‘integral’ to integrate over the removed axes or ‘average’ to perform an average instead.
label (str, optional) – The label of the returned field
- Returns:
The projected data in a scalar field with a subgrid of the original grid.
- Return type:
- slice(position, *, method='nearest', label=None)[source]
slice data at a given position
Note
This method should not be used to evaluate fields right at the boundary since it does not respect boundary conditions. Use
get_boundary_field()
to obtain the values directly on the boundary.- Parameters:
position (dict) – Determines the location of the slice using a dictionary supplying coordinate values for a subset of axes. Axes not mentioned in the dictionary are retained and form the slice. For instance, in a 2d Cartesian grid, position = {‘x’: 1} slices along the y-direction at x=1. Additionally, the special positions ‘low’, ‘mid’, and ‘high’ are supported to reference relative positions along the axis.
method (str) – The method used for slicing. Currently, we only support nearest, which takes data from cells defined on the grid.
label (str, optional) – The label of the returned field
- Returns:
The sliced data in a scalar field with a subgrid of the original grid.
- Return type:
- to_scalar(scalar='auto', *, label=None)[source]
return a modified scalar field by applying method scalar
- Parameters:
scalar (str or callable) – Determines the method used for obtaining the scalar. If this is a callable, it is simply applied to self.data and a new scalar field with this data is returned. Alternatively, pre-defined methods can be selected using strings. Here, abs and norm denote the norm of each entry of the field, while norm_squared returns the squared norm. The default auto is to return a (unchanged) copy of a real field and the norm of a complex field.
label (str, optional) – Name of the returned field
- Returns:
Scalar field after applying the operation
- Return type: