# V0.7 Scope Freeze

## Summary

`v0.7` is the first structured external-data ingestion release for `pdelie`.

Its purpose is:

> ingest external structured 1D uniform rectilinear PDE data into canonical `FieldBatch`, so the existing stable scalar Heat/Burgers symmetry and discovery stack can run on imported data rather than only internally generated synthetic fixtures.

`v0.7` is intentionally narrow.
It is not a broad dataset-adapter release.

---

## Stable Scope

Stable `v0.7` scope is limited to:

- `pdelie.data.from_numpy(...)`
- `pdelie.data.from_xarray(...)`
- strict conversion into canonical `FieldBatch`
- structured 1D uniform rectilinear trajectory data only
- scalar-variable stable slice only
- explicit dims, coords, metadata, mask, and provenance validation
- parity with the existing Heat/Burgers symmetry and discovery pipeline

Stable `v0.7` release definition:

`external structured arrays -> canonical FieldBatch -> existing PDELie pipeline`

---

## Exact Public API Contracts

Planned stable public APIs:

- `pdelie.data.from_numpy(values, *, dims, coords, var_name, metadata, mask=None, preprocess_log=None) -> FieldBatch`
- `pdelie.data.from_xarray(data_array, *, var_name=None, metadata, mask=None, preprocess_log=None) -> FieldBatch`

`from_xarray(...)` is frozen to `xarray.DataArray` only in `v0.7`.
`xarray.Dataset` support is out of scope for the stable slice.

Variable-name rules:

- `from_numpy(...)` always requires explicit `var_name`
- `from_xarray(...)` resolves `var_name` by:
  - explicit `var_name` argument first
  - otherwise the single `var` coordinate value when explicit `var` axis exists
  - otherwise `DataArray.name`
  - otherwise validation failure

---

## Accepted Layouts

Stable accepted source layouts are:

- `("time", "x")`
- `("batch", "time", "x")`
- `("time", "x", "var")`
- `("batch", "time", "x", "var")`

Frozen axis/layout rules:

- `time` is required
- `x` is required
- `var` may be omitted only for the scalar stable slice
- if `var` is omitted, the importer injects a trailing singleton `var` axis
- if `var` is present, its length must be exactly `1`
- no static / no-time layouts in stable `v0.7`
- no dim aliases in stable `v0.7`
- no `y` / `z` ingestion in stable `v0.7`

---

## Coordinate and Metadata Validation

Coordinate validation:

- `time` and `x` coordinates are required
- both must be 1D finite numeric arrays
- `time` must be strictly increasing, uniform, and length `>= 3`
- `x` must be strictly increasing, uniform, and length `>= 4`
- `x` uniformity uses the current `FieldBatch` spatial tolerance policy
- `time` uniformity is required because stable `v0.7` imports target the current trajectory / discovery pipeline
- no coordinate inference beyond extracting `time` / `x` from the provided inputs
- no normalization, sorting, or repair of malformed coordinates

Metadata requirements:

- the caller must supply the full required `FieldBatch` metadata mapping
- there is no stable metadata inference in `v0.7`
- required keys remain:
  - `boundary_conditions`
  - `grid_type`
  - `coordinate_system`
  - `grid_regularity`
  - `parameter_tags`
- stable `v0.7` imported fields must validate as:
  - `grid_type == "rectilinear"`
  - `grid_regularity == "uniform"`
  - `coordinate_system == "cartesian"`
  - `boundary_conditions["x"] == "periodic"`
- `parameter_tags` must be a mapping but may be empty
- `xarray` attrs are not used as stable metadata inference

---

## Mask / NaN Policy

Stable `v0.7` importers preserve missing-data signals rather than normalizing them.

Frozen rules:

- preserve both explicit masks and existing `NaN` / non-finite values
- do not normalize `NaN` values into masks
- do not normalize masks into `NaN` values
- if `mask` is provided and `var` is injected, inject the singleton `var` axis into the mask too
- `from_numpy(...)` accepts array-like `mask`
- `from_xarray(...)` accepts `xarray.DataArray` `mask` only
- mask must align with the pre-normalized input layout and the resulting post-injection shape

---

## Copy / Provenance Semantics

Stable importers always materialize owned canonical data.

Frozen copy rules:

- always materialize and copy imported values
- always copy coordinates
- always copy masks when present
- deep-copy `metadata`
- if `preprocess_log` is omitted, start from `[]`
- if `preprocess_log` is provided, deep-copy it and then append exactly one new entry

Frozen provenance rule:

- append exactly one provenance entry:
  - `operation = "from_numpy"` or `"from_xarray"`
  - `parameters` includes at least:
    - `source_layout`
    - `imported_shape`
    - `injected_var_axis`
    - `mask_provided`

No broader provenance schema is introduced in `v0.7 M0`.

---

## Optional `xarray` Dependency Policy

Stable dependency behavior:

- `from_numpy(...)` is core-only
- `from_xarray(...)` is a runtime-optional path
- `xarray` must be imported lazily inside the function / module path
- if `xarray` is unavailable, calling `from_xarray(...)` raises `ImportError` with an install message
- the optional dependency extra name for stable `from_xarray(...)` support is `xarray`

---

## Explicit Non-goals

Out of stable `v0.7` scope:

- no `xarray.Dataset` stable support
- no dim aliases
- no static-field ingestion
- no multidimensional ingestion
- no `y` / `z` ingestion
- no nonuniform-grid support
- no metadata inference layer
- no PDEBench-specific loader
- no The Well adapter
- no HDF5, netCDF, or Zarr stable loader
- no weak-form methods
- no operator methods
- no stable KdV promotion piggybacked into ingestion work
- no paper-specific experiment logic

---

## Milestones

Planned `v0.7` sequence:

- Milestone 0 — external ingestion contract freeze
- Milestone 1 — `from_numpy(...)`
- Milestone 2 — `from_xarray(...)`
- Milestone 3 — parity tests and compact `v0.7` release gate