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 isself.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
Axisobjects.scale_factors (sequence of callables) – One callable per axis.
scale_factors[i](meshed_coords)must return anndarrayof shapegrid.shape.cartesian (callable, optional) – Maps the tuple of meshed curvilinear coordinates to a tuple of meshed Cartesian coordinates. Used for
cartesian_coordsand 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 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
cartesianmapping.
- 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 Laplaciangradient()— gradient of a scalar fielddivergence()— divergence of a vector fieldcurl()— 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 Laplaciangradient()— gradient of a scalar fielddivergence()— divergence of a vector fieldcurl()— 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 Laplaciangradient()— gradient of a scalar fielddivergence()— divergence of a 2D vector fieldcurl()— 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.