Access grids and values directly

Postgkyl does not require you to express every calculation as a pipeline. After loading a dataset, data.grid exposes its coordinate arrays and data.values exposes the stored numbers. What those numbers mean depends on the representation: a raw modal file holds coefficients, while an interpolated dataset holds field values. np.asarray(data) also exposes point values; it deliberately refuses modal coefficients.

Use .copy() when you want independent writable arrays. Never assume that editing a view will leave its dataset unchanged. The example below copies both the grid and values, performs a NumPy calculation, and uses clone and push to create a plotted result while retaining the field metadata.

An axis with one more coordinate than its value-array dimension contains cell edges; use adjacent-edge midpoints to associate one coordinate with each cell value. If the coordinates already align one-to-one with the values, use them directly. np.meshgrid(..., indexing="ij") preserves the data’s axis order. The final array dimension indexes components, not space.

This example converts density to a normalized perturbation. Its CLI equivalent uses evaluate for the same arithmetic. The rendered pixels are checked against the manually manipulated Python arrays.

Download the example bundle first.

Python script

python examples/scripts/10_manual_arrays.py
"""Copy grids and values, manipulate the arrays, and wrap a field for plotting."""

import numpy as np
import postgkyl as pg
from _example_paths import TEST_DATA, prepare_output_dir

OUTPUT_DIR = prepare_output_dir()
modal = pg.load(TEST_DATA / "generated/wave_surface_000.gkyl")
# On modal data, these numbers are coefficients, not physical field samples.
coefficients = modal.values.copy()
assert coefficients.shape[-1] == 1  # this generated example uses p0

field = modal.interpolate()
grid = [axis.copy() for axis in field.grid]
values = field.values.copy()
np.testing.assert_array_equal(np.asarray(field), values)

# This interpolated mesh has edges. Pair its cell centers with field values;
# for data already located at nodes, use the grid coordinates directly.
coordinates = [
    0.5 * (axis[1:] + axis[:-1]) if len(axis) == values.shape[dim] + 1 else axis
    for dim, axis in enumerate(grid)
]
x, y = np.meshgrid(*coordinates, indexing="ij")
assert x.shape == y.shape == values.shape[:-1]

# NumPy edits to these copies do not change the original dataset.
manual_values = (values - 1.0) / 0.6
np.testing.assert_allclose(manual_values[..., 0],
                           np.cos(x) * np.cos(y),
                           atol=1e-14)
np.testing.assert_array_equal(field.values, values)

# push accepts coordinates and values. Preserve metadata explicitly when
# constructing a new point-value dataset after a manual calculation.
manual = field.clone()
manual.push(grid, manual_values)
manual.plot(title="Normalized density perturbation",
            xlabel="x",
            ylabel="y",
            clabel="(n - 1) / 0.6",
            no_show=True,
            saveas=OUTPUT_DIR / "10_manual.png",
            dpi=100)

Equivalent CLI commands

Run from the extracted example bundle (or repository root). Create an output directory first:

mkdir -p output
pgkyl tests/test_data/generated/wave_surface_000.gkyl interpolate evaluate 'f 1 - 0.6 /' \
    plot --title 'Normalized density perturbation' --xlabel x --ylabel y --clabel \
    '(n - 1) / 0.6' --no_show --dpi 100 --saveas output/10_manual.png

10_manual.png: Identical pixels (1 frame(s)) and timing.

Python and CLI outputs
Python output for 10_manual.png CLI output for 10_manual.png