# 4.2.5 pde.grids.cartesian module

Cartesian grids of arbitrary dimension.

class CartesianGrid(bounds, shape, periodic=False)[source]

Bases: GridBase

d-dimensional Cartesian grid with uniform discretization for each axis

The grids can be thought of as a collection of n-dimensional boxes, called cells, of equal length in each dimension. The bounds then defined the total volume covered by these cells, while the cell coordinates give the location of the box centers. We index the boxes starting from 0 along each dimension. Consequently, the cell $$i-\frac12$$ corresponds to the left edge of the covered interval and the index $$i+\frac12$$ corresponds to the right edge, when the dimension is covered by d boxes.

In particular, the discretization along dimension $$k$$ is defined as

$\begin{split}x^{(k)}_i &= x^{(k)}_\mathrm{min} + \left(i + \frac12\right) \Delta x^{(k)} \quad \text{for} \quad i = 0, \ldots, N^{(k)} - 1 \\ \Delta x^{(k)} &= \frac{x^{(k)}_\mathrm{max} - x^{(k)}_\mathrm{min}}{N^{(k)}}\end{split}$

where $$N^{(k)}$$ is the number of cells along this dimension. Consequently, cells have dimension $$\Delta x^{(k)}$$ and cover the interval $$[x^{(k)}_\mathrm{min}, x^{(k)}_\mathrm{max}]$$.

Parameters:
• bounds (list of tuple) – Give the coordinate range for each axis. This should be a tuple of two number (lower and upper bound) for each axis. The length of bounds thus determines the grid dimension.

• shape (list) – The number of support points for each axis. The length of shape needs to match the grid dimension.

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

boundary_names: dict[str, tuple[int, bool]] = {'back': (2, False), 'bottom': (1, False), 'front': (2, True), 'left': (0, False), 'right': (0, True), 'top': (1, True)}

Names of boundaries to select them conveniently

Type:

dict

property cell_volume_data

size associated with each cell

cuboid: Cuboid
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:
Returns:

The difference vectors between the points with periodic boundary conditions applied.

Return type:

ndarray

classmethod from_bounds(bounds, shape, periodic)[source]
Parameters:
• bounds (tuple) – Give the coordinate range for each axis. This should be a tuple of two number (lower and upper bound) for each axis. The length of bounds thus determines the grid dimension.

• shape (tuple) – The number of support points for each axis. The length of shape needs to match the grid dimension.

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

Returns:

representing the region chosen by bounds

Return type:

CartesianGrid

classmethod from_state(state)[source]

create a field from a stored state.

Parameters:

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

Returns:

the grid re-created from the state data

Return type:

CartesianGrid

get_image_data(data)[source]

return a 2d-image of the data

Parameters:

data (ndarray) – The values at the grid points

Returns:

A dictionary with information about the data convenient for plotting.

Return type:

dict

get_line_data(data, extract='auto')[source]

return a line cut through the given data

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

• extract (str) –

Determines which cut is done through the grid. Possible choices are (default is cut_0):

• cut_#: return values along the axis specified by # and use the mid point along all other axes.

• project_#: average values for all axes, except axis #.

Here, # can either be a zero-based index (from 0 to dim-1) or a letter denoting the axis.

Returns:

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

Return type:

dict

get_random_point(*, boundary_distance=0, coords='cartesian', rng=None)[source]

return a random point within the grid

Parameters:
Returns:

The coordinates of the point

Return type:

ndarray

get_vector_data(data, **kwargs)[source]

return data to visualize vector field

Parameters:
Returns:

A dictionary with information about the data convenient for plotting.

Return type:

dict

iter_mirror_points(point, with_self=False, only_periodic=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

Return type:

Generator

plot(*args, title=None, filename=None, action='auto', ax_style=None, fig_style=None, ax=None, **kwargs)[source]

visualize the grid

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 final figure. If the argument is set to show, matplotlib.pyplot.show() will be called to show the plot. If the value is none, the figure will be created, but not necessarily shown. 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 i 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. The special value “create” creates a new figure, while “reuse” attempts to reuse an existing figure, which is the default.

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

slice(indices)[source]

return a subgrid of only the specified axes

Parameters:

indices (list) – Indices indicating the axes that are retained in the subgrid

Returns:

The subgrid

Return type:

CartesianGrid

property state: dict[str, Any]

the state of the grid

Type:

dict

property volume: float

total volume of the grid

Type:

float

class UnitGrid(shape, periodic=False)[source]

Bases: CartesianGrid

d-dimensional Cartesian grid with unit discretization in all directions

The grids can be thought of as a collection of d-dimensional cells of unit length. The shape parameter determines how many boxes there are in each direction. The cells are enumerated starting with 0, so the last cell has index $$n-1$$ if there are $$n$$ cells along a dimension. A given cell $$i$$ extends from coordinates $$i$$ to $$i + 1$$, so the midpoint is at $$i + \frac12$$, which is the cell coordinate. Taken together, the cells covers the interval $$[0, n]$$ along this dimension.

Parameters:
• shape (list) – The number of support points for each axis. The dimension of the grid is given by len(shape).

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

classmethod from_state(state)[source]

create a field from a stored state.

Parameters:

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

Return type:

UnitGrid

slice(indices)[source]

return a subgrid of only the specified axes

Parameters:

indices (list) – Indices indicating the axes that are retained in the subgrid

Returns:

The subgrid

Return type:

UnitGrid

property state: dict[str, Any]

the state of the grid

Type:

dict

to_cartesian()[source]

convert unit grid to CartesianGrid

Returns:

The equivalent cartesian grid

Return type:

CartesianGrid