4.2.3. pde.grids.base module¶
Bases classes
- exception DimensionError[source]¶
Bases:
ValueError
exception indicating that dimensions were inconsistent
- 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: GridBase) None [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
- 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
- cell_to_point(cells: ndarray, cartesian: bool = True) ndarray [source]¶
convert cell coordinates to real coordinates
- Parameters
- Returns
The center points of the respective cells
- Return type
Warning
This method is deprecated since 2022-03-14 and will be removed soon.
- compatible_with(other: GridBase) bool [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: ndarray, *, coords: str = 'cartesian', wrap: bool = True) ndarray [source]¶
check whether the point is contained in the grid
- difference_vector_real(p1: ndarray, p2: ndarray) ndarray [source]¶
return the vector pointing from p1 to p2
In case of periodic boundary conditions, the shortest vector is returned.
- distance_real(p1: ndarray, p2: ndarray) float [source]¶
Calculate the distance between two points given in real coordinates
This takes periodic boundary conditions into account if necessary.
- classmethod from_state(state: Union[str, Dict[str, Any]]) GridBase [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.
- get_axis_index(key: Union[int, str], allow_symmetric: bool = True) int [source]¶
return the index belonging to an axis
- abstract get_boundary_conditions(bc: BoundariesData = 'auto_periodic_neumann', rank: int = 0) Boundaries [source]¶
- abstract get_random_point(*, boundary_distance: float = 0, coords: str = 'cartesian') ndarray [source]¶
- integrate(data: Union[int, float, complex, ndarray], axes: Optional[Union[int, Sequence[int]]] = None) ndarray [source]¶
Integrates the discretized data over the grid
- abstract iter_mirror_points(point: ndarray, with_self: bool = False, only_periodic: bool = True) Generator [source]¶
- make_cell_volume_compiled(flat_index: bool = False) Callable[[...], float] [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(*, full_data: bool = False) Callable[[ndarray, ndarray, Union[int, float, complex, ndarray]], None] [source]¶
return a compiled function to insert values at interpolated positions
- Parameters
full_data (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.
- make_integrator() Callable[[ndarray], ndarray] [source]¶
Return function that can be used to integrates discretized data over the grid
Note that currently only scalar fields are supported.
- 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: bool = True) Callable[[ndarray], None] [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: Union[str, OperatorInfo], bc: BoundariesData, **kwargs) Callable[..., np.ndarray] [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 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.
**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: Union[str, OperatorInfo], **kwargs) Callable[[ndarray, ndarray], None] [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: ndarray, *, reflect: bool = False) ndarray [source]¶
normalize grid coordinates by applying periodic boundary conditions
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
- Returns
The respective coordinates with periodic boundary conditions applied.
- Return type
- point_to_cell(points: ndarray) ndarray [source]¶
Determine cell(s) corresponding to given point(s)
- Parameters
points (
ndarray
) – Real coordinates- Returns
The indices of the respective cells
- Return type
Warning
This method is deprecated since 2022-03-14 and will be removed soon.
- abstract polar_coordinates_real(origin: ndarray, *, ret_angle: bool = False) Union[ndarray, Tuple[ndarray, ...]] [source]¶
- classmethod register_operator(name: str, factory_func: Optional[Callable] = None, rank_in: int = 0, rank_out: int = 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(bcs: Boundaries): ...
- Parameters
name (str) – The name of the operator to register
factory_func (callable) – A function with signature
(bcs: Boundaries, **kwargs)
, which takes boundary conditions 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: ndarray, source: str, target: str) ndarray [source]¶
converts coordinates from one coordinate system to another
Supported coordinate systems include
cartesian: Cartesian coordinates where each point carries dim values
cell: Grid coordinates based on indexing the discretization cells
grid: Grid coordinates where each point carries num_axes values
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: Callable[..., OperatorType], rank_in: int, rank_out: int, name: str = '')[source]¶
Bases:
tuple
stores information about an operator
Create new instance of OperatorInfo(factory, rank_in, rank_out, name)
- property factory¶
Alias for field number 0
- property name¶
Alias for field number 3
- property rank_in¶
Alias for field number 1
- property rank_out¶
Alias for field number 2
- exception PeriodicityError[source]¶
Bases:
RuntimeError
exception indicating that the grid periodicity is inconsistent
- discretize_interval(x_min: float, x_max: float, num: int) Tuple[ndarray, float] [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.