Curvilinear grids

Many physical problems are naturally expressed in non-Cartesian coordinates – spherical coordinates for planetary atmospheres, cylindrical coordinates for pipes, polar coordinates for 2D disk-shaped domains. numgrids provides CurvilinearGrid and six built-in coordinate systems that give you gradient, divergence, Laplacian, curl and volume integrals out of the box.

from numgrids import *
import numpy as np

How it works

An orthogonal curvilinear coordinate system is fully characterized by its scale factors \(h_i(\mathbf{q})\). Given these, the standard differential-geometry identities define all vector calculus operators:

Gradient:

\[(\nabla f)_i = \frac{1}{h_i}\frac{\partial f}{\partial q_i}\]

Divergence:

\[\nabla \cdot \mathbf{v} = \frac{1}{J}\sum_i \frac{\partial}{\partial q_i} \left(\frac{J}{h_i}\,v_i\right), \quad J = \prod_i h_i\]

Laplacian:

\[\nabla^2 f = \frac{1}{J}\sum_i \frac{\partial}{\partial q_i} \left(\frac{J}{h_i^2}\,\frac{\partial f}{\partial q_i}\right)\]

Curl (3D):

\[(\nabla \times \mathbf{v})_i = \frac{1}{h_j h_k}\left[ \frac{\partial(h_k\,v_k)}{\partial q_j} - \frac{\partial(h_j\,v_j)}{\partial q_k}\right]\]

where \((i, j, k)\) is a cyclic permutation of \((0, 1, 2)\).

CurvilinearGrid takes a set of axes and scale-factor callables, then builds these operators automatically using the grid’s differentiation machinery.

Built-in coordinate systems

SphericalSurfaceGrid \((\theta, \phi)\)

The 2D surface of a sphere of radius radius; scale factors \(h_\theta = R\), \(h_\phi = R\sin\theta\). Its Laplacian is the Laplace–Beltrami operator. Use colatitude(n) for the polar axis to cover the whole sphere (see Full disks, cylinders, spheres and balls).

sphere = SphericalSurfaceGrid(colatitude(16), periodic(32), radius=2.0)

SphericalGrid \((r, \theta, \phi)\)

Scale factors: \(h_r = 1\), \(h_\theta = r\), \(h_\phi = r\sin\theta\).

grid = SphericalGrid(
    create_axis(AxisType.CHEBYSHEV, 25, 0.5, 2.0),              # r
    create_axis(AxisType.CHEBYSHEV, 20, 0.1, np.pi - 0.1),      # theta
    create_axis(AxisType.EQUIDISTANT_PERIODIC, 30, 0, 2 * np.pi),  # phi
)

R, Theta, Phi = grid.meshed_coords
f = R**2 * np.sin(Theta)

lap_f = grid.laplacian(f)
grad_f = grid.gradient(f)           # (grad_r, grad_theta, grad_phi)

The three axes must be passed in the order \((r, \theta, \phi)\). The azimuthal axis (phi) should be periodic.

CylindricalGrid \((r, \phi, z)\)

Scale factors: \(h_r = 1\), \(h_\phi = r\), \(h_z = 1\).

grid = CylindricalGrid(
    create_axis(AxisType.CHEBYSHEV, 20, 0.1, 2.0),               # r
    create_axis(AxisType.EQUIDISTANT_PERIODIC, 30, 0, 2 * np.pi),  # phi
    create_axis(AxisType.CHEBYSHEV, 20, -1.0, 1.0),              # z
)

R, Phi, Z = grid.meshed_coords
f = R**2 + Z**2
lap_f = grid.laplacian(f)  # should be close to 6 everywhere

PolarGrid \((r, \phi)\)

Scale factors: \(h_r = 1\), \(h_\phi = r\).

grid = PolarGrid(
    create_axis(AxisType.CHEBYSHEV, 30, 0.1, 1.0),              # r
    create_axis(AxisType.EQUIDISTANT_PERIODIC, 40, 0, 2 * np.pi),  # phi
)

R, Phi = grid.meshed_coords
f = R**2 * np.cos(Phi)
lap_f = grid.laplacian(f)

EllipticCylindricalGrid \((\mu, \nu, z)\)

\(x = a\cosh\mu\cos\nu\), \(y = a\sinh\mu\sin\nu\), \(z = z\). Scale factors: \(h_\mu = h_\nu = a\sqrt{\sinh^2\mu + \sin^2\nu}\), \(h_z = 1\). Useful for elliptic domains, e.g. flows around elliptic cylinders.

elliptic = EllipticCylindricalGrid(
    chebyshev(20, 0.0, 1.0),   # mu
    periodic(40),              # nu
    chebyshev(10, -1, 1),      # z
    a=2.0,                     # focal distance
)

ProlateSpheroidalGrid and OblateSpheroidalGrid \((\mu, \nu, \phi)\)

Spheroidal coordinates for elongated (prolate, \(\nu\in[0,\pi]\)) or flattened (oblate, \(\nu\in[-\pi/2,\pi/2]\)) bodies, with focal distance a:

prolate = ProlateSpheroidalGrid(chebyshev(20, 0, 1), chebyshev(20, 0, np.pi), periodic(16), a=1.0)
oblate = OblateSpheroidalGrid(chebyshev(20, 0, 1), chebyshev(20, -np.pi/2, np.pi/2), periodic(16), a=1.0)

Axis names

The built-in grids name their axes after the coordinates (unless you named them yourself): "r", "theta", "phi", "z", "mu", "nu". So you can write grid.diff(f, axis="r") or grid.faces["r_high"].

Geometry

Every curvilinear grid exposes its geometry:

grid.scale_factors      # tuple of arrays h_i
grid.volume_element     # J = h_1 h_2 ... h_n
grid.cartesian_coords   # meshed Cartesian coordinates (X, Y[, Z])

cartesian_coords is used by grid.plot(f) to draw 2D curvilinear grids in Cartesian space.

Vector calculus operators

All curvilinear grids provide four operators:

gradient(f)

Takes a scalar field and returns a tuple of arrays, one per coordinate:

grad_r, grad_theta, grad_phi = grid.gradient(f)

divergence(v_r, v_theta, v_phi)

Takes the physical components of a vector field (one array per coordinate) and returns a scalar field:

div_v = grid.divergence(v_r, v_theta, v_phi)

laplacian(f)

Takes a scalar field and returns the scalar Laplacian:

lap_f = grid.laplacian(f)

curl(*v)

For 3D grids, takes three vector components and returns a tuple of three arrays:

curl_r, curl_theta, curl_phi = grid.curl(v_r, v_theta, v_phi)

For 2D grids (e.g. PolarGrid), takes two vector components and returns a single scalar array – the out-of-plane component:

curl_z = grid.curl(v_r, v_phi)   # scalar array

Sparse operators and integration

For solving PDEs, the Laplacian is also available as a sparse Operator:

annulus = PolarGrid(chebyshev(30, 0.5, 1.0), periodic(40))
L = annulus.laplacian_operator()
u = L.solve(1.0, bcs=0)                        # Poisson problem, u = 0 on both rims
vals, modes = (-L).eig(k=6, bcs=0)             # Laplace eigenmodes

Gradient and divergence are available as operators, too, and combine to operators in divergence form such as \(\nabla\cdot(k\,\nabla u)\) (see Operators):

G_r, G_phi = annulus.gradient_operator()       # physical components of the gradient
D_r, D_phi = annulus.divergence_operator()     # div v = D_r(v_r) + D_phi(v_phi)

R, _ = annulus.meshed_coords
L_k = annulus.diffusion_operator(1 + R**2)     # u -> div((1 + r^2) grad u)

grid.integrate(f) includes the volume element, i.e. it computes \(\int f\, dV\); see Integration.

Full disks, cylinders, spheres and balls

To include the center \(r = 0\), use a radial axis as the first axis of a PolarGrid, CylindricalGrid or SphericalGrid. To include the poles \(\theta = 0, \pi\), use a colatitude axis as the polar axis of a SphericalGrid or SphericalSurfaceGrid:

disk = PolarGrid(radial(24, 1.0), periodic(32))
cylinder = CylindricalGrid(radial(16, 1.0), periodic(32), chebyshev(16, 0, 2))
sphere = SphericalSurfaceGrid(colatitude(16), periodic(32))      # the surface
ball = SphericalGrid(radial(16, 1.0), colatitude(16), periodic(32))

The radial points are the positive half of Chebyshev nodes on the diameter \([-R, R]\); no point lies on the origin. Radial derivatives are computed on the whole diameter, using that the point \((-r, \varphi)\) is the same as \((r, \varphi + \pi)\) (and \((r, \pi - \theta, \varphi + \pi)\) on a ball).

The colatitude points are \(\theta_j = (j + \frac12)\pi/n\); no point lies on a pole. A meridian continues across a pole on the opposite side – \((2\pi - \theta, \varphi)\) is the point \((\theta, \varphi + \pi)\) – so \(\theta\)-derivatives are computed with Fourier differentiation on the full great circle (“double Fourier sphere”), and integrals use Fejér’s quadrature.

As a result

  • there is no singularity and no boundary condition at the center or the poles – the only boundary face of a disk, cylinder or ball is its outer surface "r_high" (plus the end faces of a cylinder), and a sphere surface has none,

  • derivatives, Laplacians, integrals and interpolation (also exactly at the center and the poles) are spectrally accurate,

  • operators have no spurious eigenvalues, and their spectrum is real and negative, so time stepping is stable.

disk = PolarGrid(radial(24, 1.0), periodic(32))
vals, modes = (-disk.laplacian_operator()).eig(k=6, bcs=0)
np.sqrt(vals)       # 2.4048, 3.8317, 3.8317, 5.1356, 5.1356, 5.5201 (Bessel zeros)

X, Y = disk.cartesian_coords
u = disk.laplacian_operator().solve(4.0, bcs=1.0)    # u = x^2 + y^2
disk.integrate(np.ones(disk.shape))                  # pi

On the sphere, the Laplacian is the Laplace–Beltrami operator, whose eigenvalues are \(\ell(\ell+1)\) with multiplicity \(2\ell + 1\):

sphere = SphericalSurfaceGrid(colatitude(16), periodic(32), radius=1.0)
vals, harmonics = (-sphere.laplacian_operator()).eig(k=9)
vals                                         # 0, 2, 2, 2, 6, 6, 6, 6, 6
sphere.integrate(np.ones(sphere.shape))      # 4 pi

Requirements: the azimuthal axis must be periodic over \(2\pi\) with an even number of points, and on a SphericalGrid with a radial axis the polar axis must be symmetric about \(\pi/2\) (colatitude(n) always is). A ValueError explains what is missing otherwise.

Exterior domains

For the region outside a disk, cylinder or ball, use a half line as the radial axis: semi_infinite(n, scale, low=R). The only boundary is the inner surface \(r = R\), and nothing is imposed at infinity:

shell = SphericalGrid(semi_infinite(20, scale=2.0, low=1.0), colatitude(8), periodic(8))
R, Theta, Phi = shell.meshed_coords
list(shell.faces)                                  # ['0_low']

# Screened Poisson equation lap u - u = 0 with u = 1 on the unit sphere
u = (shell.laplacian_operator() - 1).solve(0, bcs=1.0)
np.abs(u - np.exp(-(R - 1)) / R).max()             # 2e-08

This requires that the equation has only one solution that is regular at infinity; see Unbounded domains for this and for the choice of scale.

Singularity handling

Curvilinear coordinates often have singularities where scale factors vanish – for example \(r = 0\) in polar, spherical or cylindrical coordinates, or \(\theta = 0, \pi\) in spherical coordinates. At these points, expressions like \(1/h_i\) produce infinities.

  • The center \(r = 0\): use a radial axis, see above.

  • The poles \(\theta = 0, \pi\) of spherical grids: use a colatitude axis, see above.

  • For parts of a sphere or ball (e.g. a cone or a band of latitudes), use a Chebyshev polar axis that avoids the poles, such as chebyshev(n, 0.2, 1.0).

Grid points placed exactly on a singularity yield non-finite coefficients, which are replaced by zero; the resulting empty operator rows are reported by Operator.solve (error) and Operator.eig (warning).

Custom curvilinear coordinates

You can define your own orthogonal coordinate system by passing scale-factor callables directly to CurvilinearGrid. Each callable receives the tuple of meshed coordinate arrays and returns an array of the same shape.

For example, parabolic cylindrical coordinates \((\sigma, \tau, z)\) with scale factors \(h_\sigma = h_\tau = \sqrt{\sigma^2 + \tau^2}\) and \(h_z = 1\):

sigma_ax = create_axis(AxisType.CHEBYSHEV, 25, 0.1, 3.0)
tau_ax   = create_axis(AxisType.CHEBYSHEV, 25, 0.1, 3.0)
z_ax     = create_axis(AxisType.CHEBYSHEV, 20, -1.0, 1.0)

grid = CurvilinearGrid(
    sigma_ax, tau_ax, z_ax,
    scale_factors=(
        lambda c: np.sqrt(c[0]**2 + c[1]**2),   # h_sigma
        lambda c: np.sqrt(c[0]**2 + c[1]**2),   # h_tau
        lambda c: np.ones_like(c[0]),             # h_z
    ),
    # optional: mapping to Cartesian coordinates (for plotting)
    cartesian=lambda c: (c[0] * c[1], (c[1]**2 - c[0]**2) / 2, c[2]),
)

Sigma, Tau, Z = grid.meshed_coords
f = Sigma**2 - Tau**2
lap_f = grid.laplacian(f)
grad_f = grid.gradient(f)

Warning

The number of scale-factor callables must match the number of axes. A ValueError is raised otherwise.

Note

CurvilinearGrid is a subclass of Grid, so all standard grid operations (refinement, boundary faces, indexing, I/O) work exactly the same way. The built-in coordinate grids are thin subclasses of CurvilinearGrid that set the scale factors for you. Refinement preserves the grid type. Custom CurvilinearGrid instances cannot be saved with save_grid (the scale-factor functions are not serializable); the built-in grids can.