Datasets

Every algorithm is fitted to a kd.PDEDataset. Three constructors build one from data you already hold: from_arrays for fields on a regular grid, from_scatter for points that are not on one, and from_xlsx for a workbook whose columns are already coordinates and values. All three are documented under the class below.

A dataset states three things before a search can start: which fields it carries, which axes they are sampled on, and which term is the left-hand side. The requirements for each are described under Data requirements, and the datasets shipped with the package are listed under Dataset catalog.

Name	Summary
`kd.PDEDataset(name, task_type[, ...])`	Complete PDE dataset specification.
`kd.TabularDataset(X, y[, ...])`	A scalar regression dataset: features `X`, target `y`, metadata.
`kd.FieldData(name, values[, ...])`	Field data container.
`kd.AxisInfo(name, values[, ...])`	Coordinate axis information.
`kd.DataTopology(value, names[, ...])`	Data layout topology.
`kd.TaskType(value, names[, ...])`	Type of discovery task.
`kd.DatasetReport(name, topology[, ...])`	Structured result of `kd.preview_report` (JSON-dumpable, answer-blind).
`kd.FieldReport(name, dtype[, ...])`	Per-field facts of one dataset field.
`kd.AxisReport(name, n[, ...])`	Per-axis facts of one dataset axis.

PDEDataset `dataclass`

Complete PDE dataset specification.

Attributes:

name (str) –

Dataset identifier
task_type (TaskType) –

Type of problem (PDE, ODE, regression)
topology (DataTopology) –

Data layout (grid, scattered, or tabular)
axes (dict[str, AxisInfo] | None) –

Mapping from axis name to AxisInfo. GRID: each AxisInfo.values is that axis's coordinate vector (length = grid dimension size).
axis_order (list[str] | None) –

Ordered list of axis names defining tensor dimensions
fields (dict[str, FieldData] | None) –

Mapping from field name to FieldData. GRID: nD tensor shaped by axis_order. SCATTERED: 1-D per-point vector (length N). TABULAR: same-length 1-D feature and target columns.
lhs_field (str) –

Field for LHS of equation (e.g., "u")
lhs_axis (str) –

Axis for time derivative on LHS (e.g., "t" for u_t = RHS)
lhs_order (int) –

Order of the LHS derivative along lhs_axis (0 -> homogeneous / no evolution LHS with empty lhs_axis + lhs_field, 1 -> u_t, 2 -> u_tt for the wave/telegraph case). Default 1.
noise_level (float) –

Amount of noise added to data
ground_truth (str | None) –

Optional ground truth equation string

Example

dataset = PDEDataset( ... name="burgers", ... task_type=TaskType.PDE, ... axes={"x": x_axis, "t": t_axis}, ... axis_order=["x", "t"], ... fields={"u": u_field}, ... lhs_field="u", ... lhs_axis="t", ... )

spatial_axes `property`

spatial_axes: list[str]

Spatial axes derived from axis_order minus lhs_axis.

from_arrays `classmethod`

from_arrays(
    coords: dict[str, Tensor | ndarray | Sequence[float]],
    fields: dict[str, Tensor | ndarray],
    *,
    lhs: str = "u_t",
    periodic: Iterable[str] | None = None,
    name: str = "custom",
    ground_truth: str | None = None,
    dtype: dtype = float64,
) -> PDEDataset

Factory: wrap raw arrays into a PDEDataset.

Parameters:

coords (dict[str, Tensor | ndarray | Sequence[float]]) –

Mapping axis name to 1D coordinate tensor (or numpy/list). Insertion order defines axis_order.
fields (dict[str, Tensor | ndarray]) –

Mapping field name to nD field tensor whose shape matches (len(coords[axis_0]), len(coords[axis_1]), ...).
lhs (str, default: 'u_t' ) –

Combined LHS spec "{field}_{axis...}" encoding the LHS derivative via the kd naming convention. "u_t" -> field "u", axis "t", order 1 (du/dt); "u_tt" -> order 2 (the wave/telegraph LHS d²u/dt²).
periodic (Iterable[str] | None, default: None ) –

Iterable of axis names that are periodic.
name (str, default: 'custom' ) –

Dataset identifier (printed in repr).
ground_truth (str | None, default: None ) –

Optional ground-truth equation string.
dtype (dtype, default: float64 ) –

Float dtype to cast coords + fields to (default float64).

Returns:

PDEDataset –

A validated PDEDataset.

Raises:

ValueError –

If lhs spec is malformed, references a missing field/axis, or field shapes don't match coords.

Example

ds = PDEDataset.from_arrays( ... coords={"x": x_array, "t": t_array}, ... fields={"u": u_array}, # shape (len(x), len(t)) ... lhs="u_t", ... periodic={"x"}, ... )

from_scatter `classmethod`

from_scatter(
    coords: dict[str, Tensor | ndarray | Sequence[float]],
    fields: dict[str, Tensor | ndarray],
    *,
    lhs: str = "u_t",
    name: str = "custom",
    ground_truth: str | None = None,
    dtype: dtype = float64,
    allow_nan: bool = False,
) -> PDEDataset

Factory: wrap raw per-point scatter arrays into a SCATTERED dataset.

Parameters:

coords (dict[str, Tensor | ndarray | Sequence[float]]) –

Mapping axis name to a 1-D per-point coordinate array (or numpy/list). Insertion order defines axis_order.
fields (dict[str, Tensor | ndarray]) –

Mapping field name to a 1-D per-point value array of the same length N as the coords.
lhs (str, default: 'u_t' ) –

LHS spec. "u_t" (default) parses via the kd naming convention to (field, axis, order) for the evolution / wave track (pivot pinned to u_t).
name (str, default: 'custom' ) –

Dataset identifier.
ground_truth (str | None, default: None ) –

Optional ground-truth equation string.
dtype (dtype, default: float64 ) –

Float dtype to cast coords + fields to (default float64).
allow_nan (bool, default: False ) –

Whether to retain NaN values in the axes/fields. Intended for a missing-value-preserving ingress such as from_xlsx with drop_na=False; default False keeps ordinary scatter construction finite-only.

Returns:

PDEDataset –

A validated SCATTERED PDEDataset.

Raises:

ValueError –

If coords/fields is empty, a coord/field is not 1-D, the coords + fields do not share one length N, or the (non-empty) lhs spec references a missing field/axis.

from_xlsx `classmethod`

from_xlsx(
    path: str | Path,
    *,
    coords: dict[str, str],
    fields: dict[str, str],
    lhs: str = "u_t",
    name: str = "custom",
    sheet: str | int | None = None,
    header_row: int = 0,
    na_values: Sequence[str] = ("Indeterminate",),
    drop_na: bool = True,
    ground_truth: str | None = None,
    dtype: dtype = float64,
) -> PDEDataset

Build a scattered dataset from named XLSX columns.

Parameters:

path (str | Path) –

XLSX workbook to read.
coords (dict[str, str]) –

Mapping from output axis names to XLSX header names.
fields (dict[str, str]) –

Mapping from output field names to XLSX header names.
lhs (str, default: 'u_t' ) –

LHS spec; "" denotes a homogeneous steady equation.
name (str, default: 'custom' ) –

Dataset name.
sheet (str | int | None, default: None ) –

Worksheet name or zero-based worksheet position.
header_row (int, default: 0 ) –

Zero-based header-row position.
na_values (Sequence[str], default: ('Indeterminate',) ) –

String cell values to represent as NaN.
drop_na (bool, default: True ) –

Drop rows containing NaN in any selected column. When false, preserve those rows and their NaN values.
ground_truth (str | None, default: None ) –

Optional ground-truth equation string.
dtype (dtype, default: float64 ) –

Floating dtype for coordinates and field values.

get_coords

get_coords(axis: str) -> Tensor

Get coordinate values for specified axis.

Parameters:

axis (str) –

Name of the axis to retrieve.

Returns:

Tensor –

1D tensor of coordinate values.

Raises:

KeyError –

If axis not found.

get_field

get_field(name: str) -> Tensor

Get field values by name.

Parameters:

name (str) –

Name of the field to retrieve.

Returns:

Tensor –

Tensor of field values.

Raises:

KeyError –

If field not found.

get_shape

get_shape() -> tuple[int, ...]

Return data shape as tuple.

Returns:

tuple[int, ...] –

Tuple of dimensions in axis_order order.

Raises:

ValueError –

If dataset is not properly configured.

TabularDataset `dataclass`

A scalar regression dataset: features X, target y, metadata.

Attributes:

X (ndarray) –

Feature matrix shaped (n_samples, n_features).
y (ndarray) –

Target vector shaped (n_samples,).
var_names (tuple[str, ...]) –

Feature names, one per column of X.
target_name (str) –

Name of the target quantity y.
name (str) –

Stable dataset identifier.
source (str) –

Citation for where the data comes from.
description (str) –

What the rows and columns physically mean.

FieldData `dataclass`

Field data container.

Attributes:

name (str) –

Field name (e.g., "u", "v")
values (Tensor) –

nD tensor of field values, shape matches axis order
allow_nan (bool) –

Whether this ingress explicitly permits missing values

AxisInfo `dataclass`

Coordinate axis information.

Attributes:

name (str) –

User-defined axis name (e.g., "x", "t", "y")
values (Tensor) –

1D tensor of coordinate values
is_periodic (bool) –

Whether this axis has periodic boundary conditions
allow_nan (bool) –

Whether this ingress explicitly permits missing values

DataTopology

Bases: Enum

Data layout topology.

TaskType

Bases: Enum

Type of discovery task.

DatasetReport `dataclass`

Structured result of kd.preview_report (JSON-dumpable, answer-blind).

Attributes:

name (str) –

Dataset identifier.
topology (str) –

DataTopology value string ("grid" / "scattered").
axes (list[AxisReport] | None) –

Per-axis reports in axis_order; None when the dataset carries no axis payload at all (metadata-only datasets).
fields (list[FieldReport] | None) –

Per-field reports in field insertion order; None when the dataset carries no field payload at all.
lhs_field (str | None) –

LHS field name, or None when unset.
lhs_axis (str | None) –

LHS axis name, or None when unset.
lhs_label (str | None) –

Canonical name of the LHS derivative — the regression target a fit on this dataset predicts.
lhs_order (int) –

Order of the LHS derivative along lhs_axis.
warnings (list[str]) –

Human-readable warnings in the order kd.preview prints them: per axis (spacing, then small grid) in axis_order, then per field (NaN, then Inf) in insertion order, then mixed field dtypes, then unset LHS.

to_dict

to_dict() -> dict[str, Any]

Return a JSON-safe dict of the full report (MCP-boundary contract).

FieldReport `dataclass`

Per-field facts of one dataset field.

Attributes:

name (str) –

Field name as it appears in dataset.fields.
dtype (str) –

Torch dtype without the torch. prefix (e.g. "float64").
shape (tuple[int, ...]) –

Tensor shape as a tuple of ints.
min (float) –

Smallest value over the FINITE entries; NaN when nothing is finite.
max (float) –

Largest value over the finite entries; NaN when nothing is finite.
mean (float) –

Mean over the finite entries; NaN when nothing is finite.
nan_count (int) –

Number of NaN entries.
inf_count (int) –

Number of Inf entries (either sign).

to_dict

to_dict() -> dict[str, Any]

Return a JSON-safe dict of this field report.

AxisReport `dataclass`

Per-axis facts of one dataset axis.

Attributes:

name (str) –

Axis name as it appears in dataset.axis_order.
n (int) –

Number of coordinate values.
min (float) –

Smallest coordinate value.
max (float) –

Largest coordinate value.
spacing (AxisSpacing) –

Spacing verdict (see :data:AxisSpacing). The "uniform" verdict is the shared is_uniform_grid predicate the finite-difference provider uses, so the report never disagrees with the FD accept/reject decision.
step_first (float | None) –

First difference values[1] - values[0]; None when no step exists (single point, or SCATTERED topology).
step_mean (float | None) –

Mean of all first differences; None as above.
step_min (float | None) –

Smallest first difference; None as above.
step_max (float | None) –

Largest first difference; None as above.

to_dict

to_dict() -> dict[str, Any]

Return a JSON-safe dict of this axis report.

Datasets

PDEDataset dataclass

spatial_axes property

from_arrays classmethod

from_scatter classmethod

from_xlsx classmethod

get_coords

get_field

get_shape

TabularDataset dataclass

FieldData dataclass

AxisInfo dataclass

DataTopology

TaskType

DatasetReport dataclass

to_dict

FieldReport dataclass

to_dict

AxisReport dataclass

to_dict

PDEDataset `dataclass`

spatial_axes `property`

from_arrays `classmethod`

from_scatter `classmethod`

from_xlsx `classmethod`

TabularDataset `dataclass`

FieldData `dataclass`

AxisInfo `dataclass`

DatasetReport `dataclass`

FieldReport `dataclass`

AxisReport `dataclass`