Saving and loading grids¶
numgrids can persist grids and associated data arrays to disk using NumPy’s
.npz format. This is useful for checkpointing long-running computations,
sharing data between scripts, or archiving results.
from numgrids import *
import numpy as np
Saving a grid¶
Use save_grid() to write a grid and any number of named data arrays to a
file:
grid = Grid(
create_axis(AxisType.CHEBYSHEV, 40, 0.0, 1.0),
create_axis(AxisType.CHEBYSHEV, 40, 0.0, 1.0),
)
X, Y = grid.meshed_coords
temperature = np.sin(np.pi * X) * np.cos(np.pi * Y)
pressure = X**2 + Y**2
save_grid("simulation.npz", grid, temperature=temperature, pressure=pressure)
The data arrays are passed as keyword arguments. Each must have the same
shape as grid.shape.
Loading a grid¶
Use load_grid() to reconstruct the grid and retrieve the saved arrays:
grid, data = load_grid("simulation.npz")
temperature = data["temperature"]
pressure = data["pressure"]
print(grid.shape) # (40, 40)
print(temperature.shape) # (40, 40)
The .npz suffix can be omitted – it will be appended automatically if
missing.
What gets stored¶
The file contains:
JSON metadata describing the grid structure: grid class, axis types, axis parameters (number of points, low, high, periodic, name).
Named arrays for each data keyword passed to
save_grid().
The grid is reconstructed from the metadata, not from raw coordinate arrays. This means the loaded grid is an exact replica of the original (same axis types, same parameters), not just a grid with matching coordinates.
Roundtrip example¶
# Create and save
ax_r = create_axis(AxisType.LOGARITHMIC, 30, 0.01, 10.0)
ax_phi = create_axis(AxisType.EQUIDISTANT_PERIODIC, 40, 0, 2 * np.pi)
grid = PolarGrid(ax_r, ax_phi)
R, Phi = grid.meshed_coords
field = R * np.cos(Phi)
save_grid("polar_field.npz", grid, field=field)
# Load and verify
grid2, data2 = load_grid("polar_field.npz")
print(type(grid2)) # <class 'numgrids.api.PolarGrid'>
print(grid2.shape) # (30, 40)
print(np.allclose(data2["field"], field)) # True
Supported grid types¶
save_grid and load_grid work with all grid types:
GridSphericalGrid,CylindricalGrid,PolarGridEllipticCylindricalGrid,ProlateSpheroidalGrid,OblateSpheroidalGrid(including the focal parametera)
All axis types (EquidistantAxis, ChebyshevAxis, LogAxis, including
periodic equidistant axes, the radial and colatitude axes of curvilinear
grids and the axes on unbounded domains) are fully supported. Axis metadata
such as periodic, name and the scale of unbounded axes is preserved
across the roundtrip.
Note
CurvilinearGrid with custom scale factors cannot be saved directly
because the scale-factor callables are not serializable. The built-in
coordinate grids (SphericalGrid, CylindricalGrid, PolarGrid) work
because their scale factors are reconstructed from the class type.
Methods on the grid¶
grid.save(path, **data) and Grid.load(path) are shortcuts for
save_grid and load_grid:
u = grid.evaluate(lambda *coords: coords[0] ** 2)
grid.save("result.npz", u=u)
grid, data = Grid.load("result.npz")
xarray and NetCDF¶
With the optional xarray dependency
(pip install numgrids[xarray]), grids and meshed data can be converted to
labelled xarray.Dataset objects – convenient for analysis, plotting and
writing NetCDF files:
grid = Grid(x=chebyshev(30, 0, 1), y=periodic(40))
X, Y = grid.meshed_coords
ds = grid.to_xarray(u=X * np.sin(Y), v=X**2) # or to_xarray(grid, ...)
ds.to_netcdf("result.nc")
Each axis becomes a dimension coordinate named after the axis (x0, x1,
… for unnamed axes). The full grid definition is stored in the
attributes, so the grid can be reconstructed exactly:
import xarray as xr
grid, data = Grid.from_xarray(xr.open_dataset("result.nc"))
u = data["u"]
from_xarray also accepts single DataArray objects and datasets that were
not created by numgrids; in that case the axis types are inferred from the
coordinate values (equidistant, Chebyshev or logarithmic; other axis types
are only restored from datasets written by to_xarray).
VTK export for ParaView¶
For 3D rendering, slicing, streamlines and the like, fields can be written to VTK files, which ParaView, VisIt and other VTK-based tools read. No additional package is needed: numgrids writes the files itself.
disk = PolarGrid(radial(24), periodic(48))
R, Phi = disk.meshed_coords
u = (1 - R**2) * R**2 * np.cos(2 * Phi)
disk.to_vtk("disk.vts", u=u, weight=1 - R**2)
Every keyword argument is a field of the file, an array of grid shape. The
method returns the path of the file written. write_vtk("disk.vts", disk, u=u) from numgrids.vtk does the same.
Vector fields¶
A tuple with one array per axis is a vector field. As everywhere in
numgrids, it is given by its physical components along the coordinate lines
of the grid, for example \((v_r, v_\varphi)\) on a PolarGrid. Viewers expect
Cartesian components, so the vectors are converted, with the unit vectors
derived from the Cartesian mapping of the grid:
velocity = (np.zeros(disk.shape), R) # (v_r, v_phi): a rigid rotation
disk.to_vtk("flow.vts", u=u, velocity=velocity)
In the file, velocity is \((-y, x, 0)\). The conversion is also available
on its own:
from numgrids.vtk import cartesian_components
vx, vy = cartesian_components(disk, *velocity)
Time series¶
A time series is written as one .vts file per time step plus a small
.pvd collection file that lists the files with their times. Open the
.pvd file in ParaView to step through the series. The result of
evolve writes itself:
X, Y = disk.cartesian_coords
u0 = np.exp(-20 * ((X - 0.3) ** 2 + Y**2))
result = evolve(disk, 0.05 * disk.laplacian_operator(), u0, (0, 0.5),
bcs=0, method="BDF", t_eval=np.linspace(0, 0.5, 11))
result.to_vtk("heat.pvd", name="T") # heat.pvd, heat_0000.vts, ..., heat_0010.vts
For a coupled system, pass one name per field (name=("u", "v")). Any
other sequence of frames is written with grid.to_vtk_series; the frames
of a field have the shape (nt, *grid.shape):
t = np.linspace(0, 1, 5)
omega = 1 + t[:, None, None] # a rotation that speeds up
frames = np.cos(Phi - omega * t[:, None, None]) * R
spin = (np.zeros((5,) + disk.shape), omega * R)
disk.to_vtk_series("spin.pvd", t=t, u=frames, velocity=spin)
What the file contains¶
Format: VTK XML StructuredGrid (
.vts): the points of the grid in their natural order, so that the viewer knows the cells without a connectivity list.Points: the Cartesian coordinates of the grid points, for curvilinear grids from their Cartesian mapping. 1D and 2D grids lie in the plane \(z = 0\); a
SphericalSurfaceGridis the sphere in space.Fields: point data in double precision. Scalars are stored under their name, vectors with three Cartesian components. A complex field
psibecomes the arrayspsi_real,psi_imagandpsi_abs(a complex vector fieldEbecomesE_realandE_imag).Closed surfaces and volumes: a periodic direction ends one point before the period is complete, which would show as a gap. It is closed by repeating the first point. Likewise, a
radialaxis has no point at the origin and acolatitudeaxis none at the poles; these points are added, with values from the spectral interpolation. The values at the grid points themselves are written unchanged. Withclose=Falsethe file holds exactly the grid points.Encoding: the numbers are stored base64-encoded (
binary=True, the default) or as text (binary=False). Both keep the full precision.
Limits¶
Grids with more than three dimensions cannot be written. Export a lower-dimensional slice on a grid of its own.
A curvilinear grid needs a Cartesian mapping (all built-in grids have one; pass
cartesian=to aCurvilinearGridof your own).Only the origin of a
radialaxis and the poles of acolatitudeaxis are filled in. A grid that merely stops short of the origin or of the poles, such aschebyshev(n, 0.01, 1)for the radius, keeps its small hole.Where the coordinate system is singular at a grid point (for example at \(r = 0\) of a
chebyshev(n, 0, 1)radial axis), the unit vectors have no direction, and components along them are dropped there.The data is not compressed, and in a time series every file repeats the points. Large 3D series take a lot of space.
The files are meant for visualization. They cannot be read back into numgrids; use
save_gridor xarray for that.