# 4.2.6. pde.grids.spherical module¶

Spherically-symmetric grids in 2 and 3 dimensions. These are grids that only discretize the radial direction, assuming symmetry with respect to all angles. This choice implies that differential operators might not be applicable to all fields. For instance, the divergence of a vector field on a spherical grid can only be represented as a scalar field on the same grid if the θ-component of the vector field vanishes.

class PolarGrid(*args, **kwargs)[source]

2-dimensional polar grid assuming angular symmetry

Deprecated since version 0.14: (2021-05-21) Use PolarSymGrid instead.

class deprecated since 2021-05-21

deprecated: bool = True
class PolarSymGrid(radius: , shape: Union[Tuple[int], int])[source]

2-dimensional polar grid assuming angular symmetry

The angular symmetry implies that states only depend on the radial coordinate $$r$$, which is discretized uniformly as

$r_i = R_\mathrm{inner} + \left(i + \frac12\right) \Delta r \quad \text{for} \quad i = 0, \ldots, N - 1 \quad \text{with} \quad \Delta r = \frac{R_\mathrm{outer} - R_\mathrm{inner}}{N}$

where $$R_\mathrm{outer}$$ is the outer radius of the grid and $$R_\mathrm{inner}$$ corresponds to a possible inner radius, which is zero by default. The radial direction is discretized by $$N$$ support points.

Parameters
• radius (float or tuple of floats) – radius $$R_\mathrm{outer}$$ in case a simple float is given. If a tuple is supplied it is interpreted as the inner and outer radius, $$(R_\mathrm{inner}, R_\mathrm{outer})$$.

• shape (tuple or int) – A single number setting the number $$N$$ of support points along the radial coordinate

axes: List[str] = ['r']
axes_symmetric: List[str] = ['phi']

The names of the additional axes that the fields do not depend on, e.g. along which they are constant.

Type

list

cell_volume_data: Sequence[FloatNumerical]
coordinate_constraints: List[int] = [0, 1]
dim: int = 2
point_to_cartesian(points: numpy.ndarray) [source]

convert coordinates of a point to Cartesian coordinates

This function returns points along the y-coordinate, i.e, the x coordinates will be zero.

Returns

The Cartesian coordinates of the point

Return type

ndarray

class SphericalGrid(*args, **kwargs)[source]

3-dimensional spherical grid assuming spherical symmetry

Deprecated since version 0.14: (2021-05-21) Use SphericalSymGrid instead.

class deprecated since 2021-05-21

deprecated: bool = True
class SphericalSymGrid(radius: , shape: Union[Tuple[int], int])[source]

3-dimensional spherical grid assuming spherical symmetry

The symmetry implies that states only depend on the radial coordinate $$r$$, which is discretized as follows:

$r_i = R_\mathrm{inner} + \left(i + \frac12\right) \Delta r \quad \text{for} \quad i = 0, \ldots, N - 1 \quad \text{with} \quad \Delta r = \frac{R_\mathrm{outer} - R_\mathrm{inner}}{N}$

where $$R_\mathrm{outer}$$ is the outer radius of the grid and $$R_\mathrm{inner}$$ corresponds to a possible inner radius, which is zero by default. The radial direction is discretized by $$N$$ support points.

Warning

Not all results of differential operators on vectorial and tensorial fields can be expressed in terms of fields that only depend on the radial coordinate $$r$$. In particular, the gradient of a vector field can only be calculated if the azimuthal component of the vector field vanishes. Similarly, the divergence of a tensor field can only be taken in special situations.

Parameters
• radius (float or tuple of floats) – radius $$R_\mathrm{outer}$$ in case a simple float is given. If a tuple is supplied it is interpreted as the inner and outer radius, $$(R_\mathrm{inner}, R_\mathrm{outer})$$.

• shape (tuple or int) – A single number setting the number $$N$$ of support points along the radial coordinate

axes: List[str] = ['r']
axes_symmetric: List[str] = ['theta', 'phi']

The names of the additional axes that the fields do not depend on, e.g. along which they are constant.

Type

list

cell_volume_data: Sequence[FloatNumerical]
coordinate_constraints: List[int] = [0, 1, 2]
dim: int = 3
point_to_cartesian(points: numpy.ndarray) [source]

convert coordinates of a point to Cartesian coordinates

This function returns points along the z-coordinate, i.e, the x and y coordinates will be zero.

Parameters

points (ndarray) – Points given in the coordinates of the grid

Returns

The Cartesian coordinates of the point

Return type

ndarray

class SphericalSymGridBase(radius: , shape: Union[Tuple[int], int])[source]

Base class for d-dimensional spherical grids with angular symmetry

The angular symmetry implies that states only depend on the radial coordinate $$r$$, which is discretized uniformly as

$r_i = R_\mathrm{inner} + \left(i + \frac12\right) \Delta r \quad \text{for} \quad i = 0, \ldots, N - 1 \quad \text{with} \quad \Delta r = \frac{R_\mathrm{outer} - R_\mathrm{inner}}{N}$

where $$R_\mathrm{outer}$$ is the outer radius of the grid and $$R_\mathrm{inner}$$ corresponds to a possible inner radius, which is zero by default. The radial direction is discretized by $$N$$ support points.

Parameters
• radius (float or tuple of floats) – radius $$R_\mathrm{outer}$$ in case a simple float is given. If a tuple is supplied it is interpreted as the inner and outer radius, $$(R_\mathrm{inner}, R_\mathrm{outer})$$.

• shape (tuple or int) – A single number setting the number $$N$$ of support points along the radial coordinate

axes: List[str]
cell_to_point(cells: numpy.ndarray, cartesian: bool = True) [source]

convert cell coordinates to real coordinates

This function returns points restricted to the x-axis, i.e., the y-coordinate will be zero.

Parameters
• cells (ndarray) – Indices of the cells whose center coordinates are requested. This can be float values to indicate positions relative to the cell center.

• cartesian (bool) – Determines whether the point is returned in Cartesian coordinates or grid coordinates.

Returns

The center points of the respective cells

Return type

ndarray

cell_volume_data: Sequence[FloatNumerical]

the volumes of all cells

Type

tuple of ndarray

contains_point(point: numpy.ndarray) [source]

check whether the point is contained in the grid

Parameters

point (ndarray) – Coordinates of the point

difference_vector_real(p1: numpy.ndarray, p2: numpy.ndarray) [source]

return the vector pointing from p1 to p2.

In case of periodic boundary conditions, the shortest vector is returned

Parameters
Returns

The difference vectors between the points

with periodic boundary conditions applied.

Return type

ndarray

dim: int
classmethod from_state(state: Dict[str, Any]) [source]

create a field from a stored state.

Parameters

state (dict) – The state from which the grid is reconstructed.

get_boundary_conditions(bc='auto_periodic_neumann', rank: int = 0) [source]

constructs boundary conditions from a flexible data format.

If the inner boundary condition for a grid without a hole is not specified, this condition is automatically set to a vanishing derivative at $$r=0$$.

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 axis, only periodic boundary conditions are allowed (indicated by ‘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.

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_cartesian_grid(mode: str = 'valid', num: int = None) [source]

return a Cartesian grid for this spherical one

Parameters
• mode (str) – Determines how the grid is determined. Setting it to ‘valid’ (or ‘inscribed’) only returns points that are fully resolved in the spherical grid, e.g., the Cartesian grid is inscribed in the sphere. Conversely, ‘full’ (or ‘circumscribed’) returns all data, so the Cartesian grid is circumscribed.

• num (int) – Number of support points along each axis of the returned grid.

Returns

The requested grid

Return type

pde.grids.cartesian.CartesianGrid

get_image_data(data: numpy.ndarray, performance_goal: str = 'speed', fill_value: float = 0, masked: bool = True) Dict[str, Any][source]

return a 2d-image of the data

Parameters
Returns

A dictionary with information about the image, which is convenient for plotting.

get_line_data(data: numpy.ndarray, extract: str = 'auto') Dict[str, Any][source]

return a line cut along the radial axis

Parameters
• data (ndarray) – The values at the grid points

• extract (str) – Determines which cut is done through the grid. This parameter is mainly supplied for a consistent interface and has no effect for polar grids.

Returns

A dictionary with information about the line cut, which is convenient for plotting.

get_random_point(boundary_distance: float = 0, cartesian: bool = True, avoid_center: bool = False, rng: = None) [source]

return a random point within the grid

Note that these points will be uniformly distributed on the radial axis, which implies that they are not uniformly distributed in the volume.

Parameters
• boundary_distance (float) – The minimal distance this point needs to have from all boundaries.

• cartesian (bool) – Determines whether the point is returned in Cartesian coordinates or grid coordinates.

• avoid_center (bool) – Determines whether the boundary distance should also be kept from the center, i.e., whether points close to the center are returned.

• rng (Generator) – Random number generator (default: default_rng())

Returns

The coordinates of the point

Return type

ndarray

property has_hole: bool

returns whether the inner radius is larger than zero

iter_mirror_points(point: numpy.ndarray, with_self: bool = False, only_periodic: bool = True) [source]

generates all mirror points corresponding to point

Parameters
• point (ndarray) – the point within the grid

• with_self (bool) – whether to include the point itself

• only_periodic (bool) – whether to only mirror along periodic axes

Returns

A generator yielding the coordinates that correspond to mirrors

num_axes: int = 1
periodic: List[bool] = [False]
plot(*args, title: str = None, filename: str = None, action: str = 'auto', ax_style: Optional[Dict[str, Any]] = None, fig_style: Optional[Dict[str, Any]] = None, ax=None, **kwargs)[source]

visualize the spherically symmetric grid in two dimensions

Parameters
• title (str) – Title of the plot. If omitted, the title might be chosen automatically.

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

• action (str) – Decides what to do with the figure. If the argument is set to show matplotlib.pyplot.show() will be called to show the plot, if the value is create, the figure will be created, but not shown, and 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.

• ax_style (dict) – Dictionary with properties that will be changed on the axis after the plot has been drawn by calling matplotlib.pyplot.setp(). A special item in this dictionary is use_offset, which is flag that can be used to control whether offset are shown along the axes of the plot.

• 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.

• ax (matplotlib.axes.Axes) – Figure axes to be used for plotting. If None, a new figure with a single axes is created.

• **kwargs – Extra arguments are passed on the to the matplotlib plotting routines, e.g., to set the color of the lines

point_from_cartesian(points: numpy.ndarray) [source]

convert points given in Cartesian coordinates to this grid

Parameters

points (ndarray) – Points given in Cartesian coordinates.

Returns

Points given in the coordinates of the grid

Return type

ndarray

point_to_cell(points: numpy.ndarray) [source]

Determine cell(s) corresponding to given point(s)

Parameters

points (ndarray) – Real coordinates

Returns

The indices of the respective cells

Return type

ndarray

polar_coordinates_real(origin=None, *, ret_angle: bool = False, **kwargs) Union[numpy.ndarray, Tuple[numpy.ndarray, ...]][source]

return spherical coordinates associated with the grid

Parameters
• origin – Place holder variable to comply with the interface

• ret_angle (bool) – Determines whether angles are returned alongside the distance. If False only the distance to the origin is returned for each support point of the grid. If True, the distance and angles are returned. Note that in the case of spherical grids, this angle is zero by convention.

Type

float

property state: Dict[str, Any]

the state of the grid

Type

state

property volume: float

total volume of the grid

Type

float

float or ndarray