Grids

A Grid is the tensor product of one or more axes. It provides meshed coordinate arrays, boundary information, and methods for differentiation, integration, interpolation, vector calculus, refinement, plotting and I/O.

from numgrids import *
import numpy as np

Creating a grid

Pass one or more axes to the Grid constructor. The order of the axes determines the axis indices (the first axis is index 0):

ax_x = create_axis(AxisType.CHEBYSHEV, 40, 0.0, 1.0)
ax_y = create_axis(AxisType.EQUIDISTANT, 50, -1.0, 1.0)
grid = Grid(ax_x, ax_y)

Axes passed as keyword arguments are named after the keyword:

grid = Grid(x=chebyshev(40, 0.0, 1.0), y=equidistant(50, -1.0, 1.0))
grid.axis_index("y")      # 1
grid.get_axis("x")        # the Chebyshev axis

Axis names can be used wherever an axis index is expected.

1D grid

ax = create_axis(AxisType.CHEBYSHEV, 100, 0.0, 1.0)
grid = Grid(ax)
print(grid.shape)  # (100,)
print(grid.ndims)  # 1

2D grid

grid = Grid(
    create_axis(AxisType.CHEBYSHEV, 40, 0.0, 1.0),
    create_axis(AxisType.CHEBYSHEV, 60, 0.0, 2.0),
)
print(grid.shape)  # (40, 60)

3D grid

grid = Grid(
    create_axis(AxisType.CHEBYSHEV, 20, 0.0, 1.0),
    create_axis(AxisType.EQUIDISTANT_PERIODIC, 30, 0.0, 2 * np.pi),
    create_axis(AxisType.CHEBYSHEV, 20, -1.0, 1.0),
)
print(grid.shape)  # (20, 30, 20)
print(grid.ndims)  # 3

Tip

You can freely mix axis types within a single grid. For example, use a Chebyshev axis for the radial direction, a periodic equidistant axis for the angular direction, and a logarithmic axis for a third coordinate.

Grid properties

shape

A tuple of the number of points along each axis:

print(grid.shape)  # (20, 30, 20)

size

The total number of grid points (product of all axis lengths):

print(grid.size)  # 12000

ndims

The number of dimensions:

print(grid.ndims)  # 3

coords

For 1D grids, returns the 1D coordinate array directly. For multi-dimensional grids, returns a tuple of 1D coordinate arrays (one per axis):

# 1D
grid_1d = Grid(create_axis(AxisType.EQUIDISTANT, 10, 0.0, 1.0))
x = grid_1d.coords  # 1D array of length 10

# 2D
grid_2d = Grid(
    create_axis(AxisType.EQUIDISTANT, 10, 0.0, 1.0),
    create_axis(AxisType.EQUIDISTANT, 20, 0.0, 2.0),
)
x_coords, y_coords = grid_2d.coords  # two 1D arrays

meshed_coords

Returns a tuple of N-dimensional arrays (one per axis) created by numpy.meshgrid with indexing="ij". These are the arrays you use to evaluate functions on the grid:

X, Y = grid_2d.meshed_coords
f = np.sin(X) * np.cos(Y)  # shape (10, 20)

boundary

A boolean mask of shape grid.shape that is True on boundary points and False in the interior. Periodic axes have no boundary points:

grid = Grid(create_axis(AxisType.EQUIDISTANT, 5, 0.0, 1.0))
print(grid.boundary)
# [ True False False False  True]

interior

The complement of boundary: True for all points not on the boundary.

faces

A dictionary of BoundaryFace objects, one per non-periodic boundary face. Keys follow the pattern "{axis_index}_{side}":

grid = Grid(
    create_axis(AxisType.EQUIDISTANT, 10, 0.0, 1.0),
    create_axis(AxisType.EQUIDISTANT, 10, 0.0, 1.0),
)
print(grid.faces.keys())
# dict_keys(['0_low', '0_high', '1_low', '1_high'])

Periodic axes are automatically excluded:

grid = Grid(
    create_axis(AxisType.EQUIDISTANT, 10, 0.0, 1.0),
    create_axis(AxisType.EQUIDISTANT_PERIODIC, 20, 0.0, 2 * np.pi),
)
print(grid.faces.keys())
# dict_keys(['0_low', '0_high'])

Ends at infinity are not faces either: a semi_infinite axis only contributes its "low" face and an infinite axis none (see Unbounded domains).

The faces dictionary is the starting point for applying boundary conditions.

Accessing individual axes

Use get_axis() to retrieve an axis by index:

axis_0 = grid.get_axis(0)
print(axis_0)

The axes property returns the full tuple:

for ax in grid.axes:
    print(ax)

Refinement and coarsening

refine()

Returns a new grid with twice the number of points along every axis:

fine = grid.refine()
print(grid.shape)  # (10, 10)
print(fine.shape)  # (20, 20)

coarsen()

Returns a new grid with half the number of points along every axis:

coarse = grid.coarsen()
print(coarse.shape)  # (5, 5)

refine_axis(axis_index, factor)

Refines (or coarsens) a single axis by a multiplicative factor. This is useful for anisotropic refinement:

# Double only axis 0
refined = grid.refine_axis(0, factor=2.0)
print(refined.shape)  # (20, 10)

# Triple axis 1
refined = grid.refine_axis(1, factor=3.0)
print(refined.shape)  # (10, 30)

A factor less than 1 coarsens. The result is rounded to the nearest integer with a minimum of 2 points.

Working with functions on the grid

Grids come with methods for the most common operations. All of them accept axis names or indices:

grid = Grid(x=chebyshev(30, 0, 1), y=periodic(40))
f = grid.evaluate(lambda x, y: x**2 * np.sin(y))   # sample a function

grid.diff(f, axis="x")             # partial derivative d/dx
grid.diff(f, order=2, axis="y")    # second derivative d^2/dy^2
grid.integrate(f)                  # integral over the whole domain
grid.interpolate(f, (0.5, 1.0))    # value at an arbitrary point

grid.gradient(f)                   # (df/dx, df/dy)
grid.laplacian(f)                  # d^2f/dx^2 + d^2f/dy^2
grid.divergence(*grid.gradient(f))
grid.curl(f, f)                    # scalar curl in 2D, vector curl in 3D

The same methods are available on curvilinear grids, where they take the metric into account. For solving PDEs, the operators are also available as sparse Operator objects (grid.diff_operator(...), grid.laplacian_operator()).

All methods check that the arrays have the grid’s shape and raise a clear ValueError otherwise.

Grid caching

The Grid object maintains an internal cache dictionary. Operators created by the convenience functions (diff, integrate, interpolate) store themselves in this cache to avoid redundant construction:

# First call builds the Diff operator and caches it
df = diff(grid, f, order=1, axis_index=0)

# Second call with the same parameters reuses the cached operator
dg = diff(grid, g, order=1, axis_index=0)

The cache is per-grid-instance: creating a new Grid (e.g. via refine()) starts with a fresh cache. You do not need to manage the cache manually.

refine(), coarsen() and refine_axis() preserve the grid type, so refining a SphericalGrid gives a SphericalGrid again.

Visualization

For 2D or higher grids, call plot() to see the grid point distribution:

grid = Grid(
    create_axis(AxisType.CHEBYSHEV, 15, 0.0, 1.0, name="x"),
    create_axis(AxisType.CHEBYSHEV, 15, 0.0, 1.0, name="y"),
)
grid.plot()

Named axes produce labeled plot axes automatically.

To plot a function on the grid, pass it to plot(); see Plotting:

X, Y = grid.meshed_coords
grid.plot(np.sin(np.pi * X) * Y)