Curvilinear Grids

Curvilinear grids extend the base grid infrastructure to non-Cartesian coordinate systems. They provide vector calculus operators – gradient, divergence, curl, and Laplacian – that account for the metric factors of the underlying coordinate system. Concrete implementations are supplied for spherical, spherical surface, cylindrical, polar, elliptic cylindrical, prolate spheroidal and oblate spheroidal coordinates.

class numgrids.CurvilinearGrid(*axes: Axis, scale_factors: Sequence[Callable[[tuple[NDArray, ...]], NDArray]], cartesian: Callable[[tuple[NDArray, ...]], tuple[NDArray, ...]] | None = None)[source]

Orthogonal curvilinear grid with auto-generated vector calculus.

The user supplies one scale-factor callable per axis. Each callable has the signature (coords: tuple[NDArray, ...]) -> NDArray, where coords is self.meshed_coords.

From the scale factors \(h_i\) the class derives:

  • gradient

    \[(\nabla f)_i = \frac{1}{h_i}\frac{\partial f}{\partial q_i}\]
  • divergence (where \(J = \prod h_i\))

    \[\nabla\!\cdot\!\mathbf{v} = \frac{1}{J}\sum_i \frac{\partial}{\partial q_i} \!\left(\frac{J}{h_i}\,v_i\right)\]
  • 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 only)

    \[(\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]\]

For 2D grids a scalar curl is provided, equal to the out-of-plane component.

Integration (integrate()) includes the volume element \(J\).

Coordinate singularities (e.g. r = 0) are handled gracefully: non-finite values are replaced by zero.

Parameters:
  • *axes (Axis) – One or more Axis objects.

  • scale_factors (sequence of callables) – One callable per axis. scale_factors[i](meshed_coords) must return an ndarray of shape grid.shape.

  • cartesian (callable, optional) – Maps the tuple of meshed curvilinear coordinates to a tuple of meshed Cartesian coordinates. Used for cartesian_coords and plotting.

Raises:

ValueError – If the number of scale factors does not match the number of axes.

Examples

>>> from numgrids import CurvilinearGrid, create_axis, AxisType
>>> import numpy as np
>>> r_ax = create_axis(AxisType.CHEBYSHEV, 25, 0.1, 2)
>>> phi_ax = create_axis(AxisType.EQUIDISTANT_PERIODIC, 30, 0, 2 * np.pi)
>>> z_ax = create_axis(AxisType.CHEBYSHEV, 25, -1, 1)
>>> grid = CurvilinearGrid(
...     r_ax, phi_ax, z_ax,
...     scale_factors=(
...         lambda c: np.ones_like(c[0]),   # h_r = 1
...         lambda c: c[0],                  # h_phi = r
...         lambda c: np.ones_like(c[0]),   # h_z = 1
...     ),
... )
>>> R, Phi, Z = grid.meshed_coords
>>> lap = grid.laplacian(R ** 2 + Z ** 2)  # should be ~6

Constructor

Parameters:
  • axes (one or more Axis objects) – One or more axes defining the grid. The order of the axes matters! The first axis passed will have index 0.

  • named_axes (Axis objects as keyword arguments) – Further axes, appended after the positional ones in the given order. The keyword is used as the axis name.

property scale_factors: tuple[NDArray, ...]

The scale factors \(h_i\) evaluated on the grid.

property volume_element: NDArray

The volume element \(J = h_1 h_2 \cdots h_n\) on the grid.

property cartesian_coords: tuple[NDArray, ...]

Meshed Cartesian coordinates of the grid points.

Raises:

NotImplementedError – If the grid was created without a cartesian mapping.

gradient(f: NDArray) → tuple[NDArray, ...][source]

Gradient of a scalar field.

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

f (NDArray) – Scalar field of shape grid.shape.

Returns:

Physical gradient components, one per axis.

Return type:

tuple of NDArray

divergence(*v: NDArray) → NDArray[source]

Divergence of a vector field.

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

*v (NDArray) – Physical components of the vector field (one per axis).

Returns:

The scalar divergence field.

Return type:

NDArray

Raises:

ValueError – If the number of components does not match the grid dimension.

gradient_operator() → tuple[Operator, ...][source]

The components of the gradient as operators, \(G_i = h_i^{-1}\,\partial_i\).

divergence_operator() → tuple[Operator, ...][source]

The divergence as one operator per vector component.

\(\nabla\cdot\mathbf{v} = \sum_i D_i v_i\) with \(D_i = J^{-1}\,\partial_i\,(J/h_i)\).

laplacian(f: NDArray) → NDArray[source]

Laplacian of a scalar field.

\[\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)\]
Parameters:

f (NDArray) – Scalar field of shape grid.shape.

Returns:

The Laplacian, same shape as f.

Return type:

NDArray

laplacian_operator(acc: int = 4) → Operator[source]

The Laplacian as a sparse Operator.

\[L = \operatorname{diag}(1/J) \sum_i \left[ \operatorname{diag}(c_i)\, D_i^{(2)} + \operatorname{diag}(\partial_i c_i)\, D_i^{(1)} \right], \qquad c_i = J/h_i^2\]

Rows at coordinate singularities (where the coefficients are not finite) are set to zero, consistent with laplacian().

curl(*v: NDArray) → tuple[NDArray, ...] | NDArray[source]

Curl of a vector field.

3D grids — returns a tuple of three arrays (one per component):

\[(\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)\).

2D grids — returns a scalar array (the out-of-plane component):

\[(\nabla\!\times\!\mathbf{v})_z = \frac{1}{h_0 h_1}\!\left[ \frac{\partial(h_1\,v_1)}{\partial q_0} - \frac{\partial(h_0\,v_0)}{\partial q_1}\right]\]
Parameters:

*v (NDArray) – Physical components of the vector field.

Returns:

The curl components.

Return type:

tuple of NDArray (3D) or NDArray (2D)

Raises:

ValueError – If the grid dimension is not 2 or 3, or if the number of components is wrong.

class numgrids.SphericalGrid(raxis: Axis, theta_axis: Axis, phi_axis: Axis)[source]

A grid in spherical coordinates \((r, \theta, \varphi)\).

\[x = r\sin\theta\cos\varphi, \quad y = r\sin\theta\sin\varphi, \quad z = r\cos\theta; \qquad h_r = 1,\ h_\theta = r,\ h_\varphi = r\sin\theta\]

Provides built-in vector calculus operators:

  • laplacian() — scalar Laplacian

  • gradient() — gradient of a scalar field

  • divergence() — divergence of a vector field

  • curl() — curl of a vector field

Coordinate singularities at r = 0 and theta = 0, pi are handled gracefully: non-finite values are replaced by zero. Unnamed axes are named "r", "theta" and "phi".

Examples

>>> import numpy as np
>>> from numgrids import SphericalGrid, chebyshev, periodic
>>> grid = SphericalGrid(chebyshev(20, 0, 1), chebyshev(20, 0, np.pi), periodic(20))
>>> round(grid.integrate(np.ones(grid.shape)), 8) == round(4 / 3 * np.pi, 8)
True

Constructor

Parameters:
  • raxis (Axis) – The radial axis.

  • theta_axis (Axis) – The polar axis (theta).

  • phi_axis (Axis) – The azimuthal axis (phi). Must be periodic.

class numgrids.SphericalSurfaceGrid(theta_axis: Axis, phi_axis: Axis, radius: float = 1.0)[source]

A 2D grid on the surface of a sphere of radius R, coordinates \((\theta, \varphi)\).

\[x = R\sin\theta\cos\varphi, \quad y = R\sin\theta\sin\varphi, \quad z = R\cos\theta; \qquad h_\theta = R,\ h_\varphi = R\sin\theta\]

The Laplacian is the Laplace–Beltrami operator of the sphere, whose eigenfunctions are the spherical harmonics. With a colatitude() axis the whole sphere including both poles is covered with spectral accuracy:

Examples

>>> import numpy as np
>>> from numgrids import SphericalSurfaceGrid, colatitude, periodic
>>> sphere = SphericalSurfaceGrid(colatitude(16), periodic(32))
>>> vals, _ = (-sphere.laplacian_operator()).eig(k=9)
>>> np.round(vals, 8) + 0.0     # l (l + 1) with multiplicity 2 l + 1
array([0., 2., 2., 2., 6., 6., 6., 6., 6.])
>>> round(sphere.integrate(np.ones(sphere.shape)), 12) == round(4 * np.pi, 12)
True

Unnamed axes are named "theta" and "phi".

Parameters:
  • theta_axis (Axis) – Polar angle (e.g. colatitude()) and azimuth (periodic over \(2\pi\)).

  • phi_axis (Axis) – Polar angle (e.g. colatitude()) and azimuth (periodic over \(2\pi\)).

  • radius (float) – Radius R of the sphere (default 1).

Constructor

Parameters:
  • axes (one or more Axis objects) – One or more axes defining the grid. The order of the axes matters! The first axis passed will have index 0.

  • named_axes (Axis objects as keyword arguments) – Further axes, appended after the positional ones in the given order. The keyword is used as the axis name.

class numgrids.CylindricalGrid(raxis: Axis, phi_axis: Axis, zaxis: Axis)[source]

A grid in cylindrical coordinates \((r, \varphi, z)\).

\[x = r\cos\varphi, \quad y = r\sin\varphi, \quad z = z; \qquad h_r = 1,\ h_\varphi = r,\ h_z = 1\]

Provides built-in vector calculus operators:

  • laplacian() — scalar Laplacian

  • gradient() — gradient of a scalar field

  • divergence() — divergence of a vector field

  • curl() — curl of a vector field

Coordinate singularities at r = 0 are handled gracefully. Unnamed axes are named "r", "phi" and "z".

Examples

>>> from numgrids import *
>>> import numpy as np
>>> grid = CylindricalGrid(
...     create_axis(AxisType.CHEBYSHEV, 20, 0.1, 2),
...     create_axis(AxisType.EQUIDISTANT_PERIODIC, 30, 0, 2 * np.pi),
...     create_axis(AxisType.CHEBYSHEV, 20, -1, 1),
... )
>>> R, Phi, Z = grid.meshed_coords
>>> f = R ** 2 + Z ** 2
>>> lap_f = grid.laplacian(f)  # should be ~6

Constructor

Parameters:
  • raxis (Axis) – The radial axis.

  • phi_axis (Axis) – The azimuthal axis (phi). Should typically be periodic.

  • zaxis (Axis) – The axial (z) axis.

class numgrids.PolarGrid(raxis: Axis, phi_axis: Axis)[source]

A 2D grid in polar coordinates \((r, \varphi)\).

\[x = r\cos\varphi, \quad y = r\sin\varphi; \qquad h_r = 1,\ h_\varphi = r\]

Provides built-in vector calculus operators:

  • laplacian() — scalar Laplacian

  • gradient() — gradient of a scalar field

  • divergence() — divergence of a 2D vector field

  • curl() — curl (returns the scalar z-component)

Coordinate singularities at r = 0 are handled gracefully. Unnamed axes are named "r" and "phi".

Examples

>>> from numgrids import *
>>> import numpy as np
>>> grid = PolarGrid(
...     create_axis(AxisType.CHEBYSHEV, 30, 0.1, 1),
...     create_axis(AxisType.EQUIDISTANT_PERIODIC, 40, 0, 2 * np.pi),
... )
>>> R, Phi = grid.meshed_coords
>>> f = R ** 2 * np.cos(Phi)
>>> lap_f = grid.laplacian(f)

Constructor

Parameters:
  • raxis (Axis) – The radial axis.

  • phi_axis (Axis) – The azimuthal axis (phi). Should typically be periodic.

class numgrids.EllipticCylindricalGrid(mu_axis: Axis, nu_axis: Axis, zaxis: Axis, a: float = 1.0)[source]

A grid in elliptic cylindrical coordinates \((\mu, \nu, z)\).

\[x = a\cosh\mu\cos\nu, \quad y = a\sinh\mu\sin\nu, \quad z = z; \qquad h_\mu = h_\nu = a\sqrt{\sinh^2\mu + \sin^2\nu},\ h_z = 1\]

Typically \(\mu \ge 0\) and \(\nu \in [0, 2\pi)\) (periodic). The foci are located at \(x = \pm a\). Unnamed axes are named "mu", "nu" and "z".

Parameters:
  • mu_axis (Axis) – The coordinate axes.

  • nu_axis (Axis) – The coordinate axes.

  • zaxis (Axis) – The coordinate axes.

  • a (float) – Focal distance (default 1).

Constructor

Parameters:
  • axes (one or more Axis objects) – One or more axes defining the grid. The order of the axes matters! The first axis passed will have index 0.

  • named_axes (Axis objects as keyword arguments) – Further axes, appended after the positional ones in the given order. The keyword is used as the axis name.

class numgrids.ProlateSpheroidalGrid(mu_axis: Axis, nu_axis: Axis, phi_axis: Axis, a: float = 1.0)[source]

A grid in prolate spheroidal coordinates \((\mu, \nu, \varphi)\).

\[x = a\sinh\mu\sin\nu\cos\varphi, \quad y = a\sinh\mu\sin\nu\sin\varphi, \quad z = a\cosh\mu\cos\nu\]
\[h_\mu = h_\nu = a\sqrt{\sinh^2\mu + \sin^2\nu}, \quad h_\varphi = a\sinh\mu\sin\nu\]

Typically \(\mu \ge 0\), \(\nu \in [0, \pi]\) and \(\varphi \in [0, 2\pi)\) (periodic). The foci are located on the z-axis at \(z = \pm a\). Unnamed axes are named "mu", "nu" and "phi".

Parameters:
  • mu_axis (Axis) – The coordinate axes.

  • nu_axis (Axis) – The coordinate axes.

  • phi_axis (Axis) – The coordinate axes.

  • a (float) – Focal distance (default 1).

Constructor

Parameters:
  • axes (one or more Axis objects) – One or more axes defining the grid. The order of the axes matters! The first axis passed will have index 0.

  • named_axes (Axis objects as keyword arguments) – Further axes, appended after the positional ones in the given order. The keyword is used as the axis name.

class numgrids.OblateSpheroidalGrid(mu_axis: Axis, nu_axis: Axis, phi_axis: Axis, a: float = 1.0)[source]

A grid in oblate spheroidal coordinates \((\mu, \nu, \varphi)\).

\[x = a\cosh\mu\cos\nu\cos\varphi, \quad y = a\cosh\mu\cos\nu\sin\varphi, \quad z = a\sinh\mu\sin\nu\]
\[h_\mu = h_\nu = a\sqrt{\sinh^2\mu + \sin^2\nu}, \quad h_\varphi = a\cosh\mu\cos\nu\]

Typically \(\mu \ge 0\), \(\nu \in [-\pi/2, \pi/2]\) and \(\varphi \in [0, 2\pi)\) (periodic). The focal ring has radius a in the xy-plane. Unnamed axes are named "mu", "nu" and "phi".

Parameters:
  • mu_axis (Axis) – The coordinate axes.

  • nu_axis (Axis) – The coordinate axes.

  • phi_axis (Axis) – The coordinate axes.

  • a (float) – Radius of the focal ring (default 1).

Constructor

Parameters:
  • axes (one or more Axis objects) – One or more axes defining the grid. The order of the axes matters! The first axis passed will have index 0.

  • named_axes (Axis objects as keyword arguments) – Further axes, appended after the positional ones in the given order. The keyword is used as the axis name.