4.2.4 pde.grids.base module
Defines the base class for all grids
- exception DomainError[source]
Bases:
ValueError
exception indicating that point lies outside domain
- class GridBase[source]
Bases:
object
Base class for all grids defining common methods and interfaces
initialize the grid
- assert_grid_compatible(other)[source]
checks whether other is compatible with the current grid
- Parameters:
other (
GridBase
) – The grid compared to this one- Raises:
ValueError – if grids are not compatible
- Return type:
None
- axes_symmetric: list[str] = []
The names of the additional axes that the fields do not depend on, e.g. along which they are constant.
- Type:
- boundary_names: dict[str, tuple[int, bool]] = {}
Names of boundaries to select them conveniently
- Type:
- c: CoordinatesBase
Coordinates of the grid
- Type:
CoordinatesBase
- cell_volume_data: Sequence[FloatNumerical] | None
Information about the size of discretization cells
- Type:
- compatible_with(other)[source]
tests whether this grid is compatible with other grids.
Grids are compatible when they cover the same area with the same discretization. The difference to equality is that compatible grids do not need to have the same periodicity in their boundaries.
- contains_point(points, *, coords='cartesian', full=False)[source]
check whether the point is contained in the grid
- Parameters:
- Returns:
A boolean array indicating which points lie within the grid
- Return type:
- difference_vector(p1, p2, *, coords='grid')[source]
return Cartesian vector(s) pointing from p1 to p2
In case of periodic boundary conditions, the shortest vector is returned.
- Parameters:
p1 (
ndarray
) – First point(s)p2 (
ndarray
) – Second point(s)coords (str) – The coordinate system in which the points are specified. Valid values are cartesian, cell, and grid; see
transform()
.
- Returns:
The difference vectors between the points with periodic boundary conditions applied.
- Return type:
- distance(p1, p2, *, coords='grid')[source]
Calculate the distance between two points given in real coordinates
This takes periodic boundary conditions into account if necessary.
- Parameters:
p1 (
ndarray
) – First positionp2 (
ndarray
) – Second positioncoords (str) – The coordinate system in which the points are specified. Valid values are cartesian, cell, and grid; see
transform()
.
- Returns:
Distance between the two positions
- Return type:
- classmethod from_state(state)[source]
create a field from a stored state.
- Parameters:
state (str or dict) – The state from which the grid is reconstructed. If state is a string, it is decoded as JSON, which should yield a dict.
- Returns:
Grid re-created from the state
- Return type:
- get_boundary_conditions(bc='auto_periodic_neumann', rank=0)[source]
constructs boundary conditions from a flexible data format
- Parameters:
bc (str or list or tuple or dict) – 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.
rank (int) – The tensorial rank of the value associated with the boundary conditions.
- Returns:
The boundary conditions for all axes.
- Return type:
- Raises:
ValueError – If the data given in bc cannot be read
PeriodicityError – If the boundaries are not compatible with the periodic axes of the grid.
- get_random_point(*, boundary_distance=0, coords='cartesian', rng=None)[source]
return a random point within the grid
- Parameters:
boundary_distance (float) – The minimal distance this point needs to have from all boundaries.
coords (str) – Determines the coordinate system in which the point is specified. Valid values are cartesian, cell, and grid; see
transform()
.rng (
Generator
) – Random number generator (default:default_rng()
)
- Returns:
The coordinates of the random point
- Return type:
- get_vector_data(data, **kwargs)[source]
return data to visualize vector field
- Parameters:
data (
ndarray
) – The vectorial values at the grid points**kwargs – Arguments forwarded to
get_image_data()
.
- Returns:
A dictionary with information about the data convenient for plotting.
- Return type:
- iter_mirror_points(point, with_self=False, only_periodic=True)[source]
generates all mirror points corresponding to point
- make_cell_volume_compiled(flat_index=False)[source]
return a compiled function returning the volume of a grid cell
- Parameters:
flat_index (bool) – When True, cell_volumes are indexed by a single integer into the flattened array.
- Returns:
returning the volume of the chosen cell
- Return type:
function
- make_inserter_compiled(*, with_ghost_cells=False)[source]
return a compiled function to insert values at interpolated positions
- Parameters:
with_ghost_cells (bool) – Flag indicating that the interpolator should work on the full data array that includes values for the grid points. If this is the case, the boundaries are not checked and the coordinates are used as is.
- Returns:
A function with signature (data, position, amount), where data is the numpy array containing the field data, position is denotes the position in grid coordinates, and amount is the that is to be added to the field.
- Return type:
callable
- make_integrator()[source]
return function that can be used to integrates discretized data over the grid
If this function is used in a multiprocessing run (using MPI), the integrals are performed on all subgrids and then accumulated. Each process then receives the same value representing the global integral.
- Returns:
A function that takes a numpy array and returns the integral with the correct weights given by the cell volumes.
- Return type:
callable
- make_normalize_point_compiled(reflect=True)[source]
return a compiled function that normalizes a point
Here, the point is assumed to be specified by the physical values along the non-symmetric axes of the grid. Normalizing points is useful to make sure they lie within the domain of the grid. This function respects periodic boundary conditions and can also reflect points off the boundary.
- Parameters:
reflect (bool) – Flag determining whether coordinates along non-periodic axes are reflected to lie in the valid range. If False, such coordinates are left unchanged and only periodic boundary conditions are enforced.
- Returns:
A function that takes a
ndarray
as an argument, which describes the coordinates of the points. This array is modified in-place!- Return type:
callable
- make_operator(operator, bc, **kwargs)[source]
return a compiled function applying an operator with boundary conditions
The returned function takes the discretized data on the grid as an input and returns the data to which the operator operator has been applied. The function only takes the valid grid points and allocates memory for the ghost points internally to apply the boundary conditions specified as bc. Note that the function supports an optional argument out, which if given should provide space for the valid output array without the ghost cells. The result of the operator is then written into this output array. The function also accepts an optional parameter args, which is forwarded to set_ghost_cells.
- Parameters:
operator (str) – Identifier for the operator. Some examples are ‘laplace’, ‘gradient’, or ‘divergence’. The registered operators for this grid can be obtained from the
operators
attribute.bc (str or list or tuple or dict) – 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.
**kwargs – Specifies extra arguments influencing how the operator is created.
- Returns:
the function that applies the operator. This function has the signature (arr: np.ndarray, out: np.ndarray = None, args=None).
- Return type:
callable
- make_operator_no_bc(operator, **kwargs)[source]
return a compiled function applying an operator without boundary conditions
A function that takes the discretized full data as an input and an array of valid data points to which the result of applying the operator is written.
Note
The resulting function does not check whether the ghost cells of the input array have been supplied with sensible values. It is the responsibility of the user to set the values of the ghost cells beforehand. Use this function only if you absolutely know what you’re doing. In all other cases,
make_operator()
is probably the better choice.- Parameters:
- Returns:
the function that applies the operator. This function has the signature (arr: np.ndarray, out: np.ndarray), so they out array need to be supplied explicitly.
- Return type:
callable
- normalize_point(point, *, reflect=False)[source]
normalize grid coordinates by applying periodic boundary conditions
Here, points are assumed to be specified by the physical values along the non-symmetric axes of the grid, e.g., by grid coordinates. Normalizing points is useful to make sure they lie within the domain of the grid. This function respects periodic boundary conditions and can also reflect points off the boundary if reflect = True.
- Parameters:
point (
ndarray
) – Coordinates of a single point or an array of points, where the last axis denotes the point coordinates (e.g., a list of points).reflect (bool) – Flag determining whether coordinates along non-periodic axes are reflected to lie in the valid range. If False, such coordinates are left unchanged and only periodic boundary conditions are enforced.
- Returns:
The respective coordinates with periodic boundary conditions applied.
- Return type:
- point_from_cartesian(points, *, full=False)[source]
convert points given in Cartesian coordinates to grid coordinates
- point_to_cartesian(points, *, full=False)[source]
convert coordinates of a point in grid coordinates to Cartesian coordinates
- classmethod register_operator(name, factory_func=None, rank_in=0, rank_out=0)[source]
register an operator for this grid
Example
The method can either be used directly:
GridClass.register_operator("operator", make_operator)
or as a decorator for the factory function:
@GridClass.register_operator("operator") def make_operator(grid: GridBase): ...
- Parameters:
name (str) – The name of the operator to register
factory_func (callable) – A function with signature
(grid: GridBase, **kwargs)
, which takes a grid object and optional keyword arguments and returns an implementation of the given operator. This implementation is a function that takes andarray
of discretized values as arguments and returns the resulting discretized data in andarray
after applying the operator.rank_in (int) – The rank of the input field for the operator
rank_out (int) – The rank of the field that is returned by the operator
- transform(coordinates, source, target, *, full=False)[source]
converts coordinates from one coordinate system to another
Supported coordinate systems include the following:
- cartesian:
Cartesian coordinates where each point carries dim values. These are the true physical coordinates in space.
- grid:
Coordinates values in the coordinate system defined by the grid. A point is thus characterized by grid.num_axes values.
- cell:
Normalized grid coordinates based on indexing the discretization cells. A point is characterized by grid.num_axes values and the range of values for a given axis is between 0 and N, where N is the number of grid points. Consequently, the integral part of the cell coordinate denotes the cell, while the fractional part denotes the relative position within the cell. In particular, the cell center is located at i + 0.5 with i = 0, …, N-1.
Note
Some conversion might involve projections if the coordinate system imposes symmetries. For instance, converting 3d Cartesian coordinates to grid coordinates in a spherically symmetric grid will only return the radius from the origin. Conversely, converting these grid coordinates back to 3d Cartesian coordinates will only return coordinates along a particular ray originating at the origin.
- class OperatorInfo(factory, rank_in, rank_out, name='')[source]
Bases:
NamedTuple
stores information about an operator
Create new instance of OperatorInfo(factory, rank_in, rank_out, name)
- Parameters:
factory (OperatorFactory) –
rank_in (int) –
rank_out (int) –
name (str) –
- factory: OperatorFactory
Alias for field number 0
- exception PeriodicityError[source]
Bases:
RuntimeError
exception indicating that the grid periodicity is inconsistent
- discretize_interval(x_min, x_max, num)[source]
construct a list of equidistantly placed intervals
The discretization is defined as
\[\begin{split}x_i &= x_\mathrm{min} + \left(i + \frac12\right) \Delta x \quad \text{for} \quad i = 0, \ldots, N - 1 \\ \Delta x &= \frac{x_\mathrm{max} - x_\mathrm{min}}{N}\end{split}\]where \(N\) is the number of intervals given by num.