Refactor of postgkyl

.agents/.gitignore

@@ -0,0 +1,7 @@
+*.md
+!CLAUDE.md
+
+# Shared, versioned repository skills.
+!skills/
+!skills/**/
+!skills/**/SKILL.md

.agents/skills/postgkyl-api-cli/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: postgkyl-api-cli
+description: Add or change public Postgkyl verbs, signatures, fluent aliases, or generated CLI behavior while preserving API/CLI parity.
+---
+
+# Keep one executable public API
+
+Core operations use `op(data: GDataState, *, ..., inplace=False, tag=None,
+label=None) -> GDataState`; funnel mutation/new-result decisions through `_result`.
+
+- Alias exact fluent verbs in the GData class body to canonical operations; no
+  wrappers, runtime setattr, or lazy imports. GDataGroup broadcasts member verbs.
+  Multi-dataset verbs share the aliases in `gdata/verbs.py`.
+- Rendering lives in `render/`. Facade, operations, fluent methods, and generated
+  CLI refer to the same canonical callables.
+- Every public boolean defaults to `False`. For enabled default behavior, name
+  its inverse (`no_show`, `volume`, `nodal`) and implement it under the false
+  branch. CLI bare boolean options mean True; explicit True/False remain accepted.
+- Expose basis/order/value_form overrides only at load time, never downstream.
+
+The CLI discovers the public API, constructs CommandSpec records, and lowers them
+through one generic compiler. Keep scientific command knowledge in API signatures,
+annotations, docstrings, and command metadata. Do not add handwritten subcommands
+or a `cli/commands/` package.
+
+Preserve underscores exactly (`local_poly`, `--num_moms`). Assign a short option
+to the first parameter with each initial in signature order; reserve `-h` for
+help. Aliases/abbreviations change spelling only. Bare filenames expand to
+`load --file_name`; they do not define different loading semantics.
+
+Use native Click chaining and callback-before-dispatch. Help groups the flat
+inventory into Verbs, Diagnostics, Render, and Utility. The console entry point
+is `postgkyl.cli.app:cli`. Version reporting is owned by `_version.py`, exported
+through the facade, and receives the version string explicitly to avoid an import
+ordering dependency; preserve its build/dependency diagnostics.
+
+Verify signature changes with `tests/test_cli_generator.py`,
+`tests/test_cli_commands.py`, and relevant diagnostic CLI tests; check canonical
+callable identities in `tests/test_postgkyl.py` when changing aliases.

.agents/skills/postgkyl-architecture/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: postgkyl-architecture
+description: Place modules and enforce import boundaries when adding or refactoring Postgkyl operations, diagnostics, rendering, or public surfaces.
+---
+
+# Preserve layer ownership
+
+`tests/test_postgkyl.py::_ALLOWED` and its AST checks are the authority for
+allowed imports and acyclicity. Consult that mapping for exact edges; when
+adding a top-level module or allowed edge, update the contract and this guidance
+in the same change if ownership changes. Do not maintain a second import matrix.
+
+| Layer | Owns |
+| --- | --- |
+| `__init__.py`, `cli/`, `gui/` | Public surfaces; the facade only re-exports, with no function/class definitions |
+| `diagnostics/` | Equation-specific physical conclusions and compositions |
+| `gdata/` | Fluent GData/GDataGroup API and load entry point |
+| `operations/` | Data transformations; flat equation-blind verbs |
+| `render/` | Canonical plotting and animation callables |
+| `gdatastate/` | State, clone, `_result`, shared guards and point-value materialization; no verbs |
+| `dg/`, `io/` | Kernel orchestration and file I/O respectively |
+| `numerics/`, `cli_spec.py` | Pure math and frozen command metadata; no internal imports |
+| `gpython/` | Sole foreign-library boundary |
+
+Imports point downward along allowed edges, never back to a higher surface.
+Operations accept GDataState; `_result` constructs `type(self)` so fluent results
+remain GData without importing gdata. Reuse `gdatastate/guards.py` and
+`materialize.py` instead of duplicating capability checks or native bridges.
+Readers return `(grid, values)` and fill plain metadata; they never import state.
+
+Diagnostics are free functions under model families `gk`, `vm`, `pkpm`, or `mom`,
+not GData methods. Model-specific loading belongs beside its physics. Resolve
+output stems/frames through `diagnostics/discovery.py`; keep quantity vocabulary
+in the equation module's `VARIABLES` table. Use public functions from lower
+layers and return a state via `_result`, or a Figure for program diagnostics.
+for the current major version.
+
+Run the import, foreign-floor, facade, and canonical-callable contracts in
+`tests/test_postgkyl.py` after structural changes.

.agents/skills/postgkyl-data/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: postgkyl-data
+description: Preserve DG representation and backend semantics when changing loading, arithmetic, conversions, integration, or terminal data consumers.
+---
+
+# Preserve data meaning
+
+Storage (`backend`: `gkyl` or `numpy`) and representation
+(`ctx["value_form"]`: `modal`, `nodal`, or `quad`) are separate facts. Do not
+add an `is_modal` flag or infer point-value capabilities from storage alone.
+
+- Modal coefficients use Gkeyll DG operations: weak multiply/divide, coefficient
+  linear combinations, scalar scaling/mean shifts, repeated weak multiplication
+  for integer powers, and native integration. Ufuncs, array conversion, selection,
+  and plotting must not treat coefficients as field values.
+- Nodal and quadrature values are fields at points. Pointwise NumPy operations
+  are allowed; native results wrap back into native storage in the same value_form.
+  Plot true point locations; non-tensor node sets use explicit `.to_quad()`.
+- Reject mixed backends or mixed value_forms when combining datasets.
+- `.interpolate()` is the one-way bridge to a new, by-value NumPy field array.
+  Interpolation matrices come from Gkeyll basis functions, applied per cell;
+  nodal input first uses the exact nodal-to-modal transform.
+- Only explicit `.to_modal()`, `.to_nodal()`, and `.to_quad()` perform representation
+  conversions. `.apply(fn, num_quad=...)` spells modal → quad → fn → projection,
+  equivalent to `fn(d.to_quad()).to_modal()`. Respect quadrature exactness limits.
+- Full modal integration is terminal and native; partial integration uses native
+  averaging with physical-volume scaling and returns lower-dimensional modal data.
+  `.average()` and `.eval_at_coord_proj()` likewise stay modal/native and compose.
+  `.local_poly()` builds a discontinuity-preserving plotting mesh.
+
+Resolve `basis_type`, `poly_order`, and `value_form` once from file metadata or
+explicit load options. Downstream verbs read ctx and raise if required metadata
+is missing; never add basis/order override parameters to them.
+
+For spatial data with unresolved basis metadata, loading warns and defaults to
+serendipity p0 nodal data. When value_form is defaulted, express the grid as cell
+centers, matching one point per cell. Dynvectors have no spatial DG basis and
+are exempt. The readers' narrower case—known basis but no value_form tag—assumes
+modal silently; keep these two defaults distinct.
+
+Route results through `_result` and terminal native point-value consumers through
+`gdatastate.materialize_point_values`. Preserve native ownership and read-only
+coefficient views; use the existing representation tests to verify semantics.

.agents/skills/postgkyl-design/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: postgkyl-design
+description: Apply Postgkyl coding doctrine when designing, implementing, or reviewing Python changes.
+---
+
+# Coding Doctrine
+
+**0. Locality of reasoning.** Every principle below is a projection of
+one axiom: a reader must be able to understand a fragment without the
+whole program. Whatever keeps a local conclusion sound — a frozen
+record, an honest signature, a stated law — is doctrine. Whatever
+forces a global search — ambient state, a leaky layer, a second copy
+of a fact — is the enemy.
+
+*Data — what it does, and what it may say*
+
+**I. Data is inert. Functions transform.** No objects that know
+things and do things. Data is a frozen record. Behavior is a function
+that takes data in and returns data out. If you're reaching for
+inheritance, you've taken a wrong turn.
+
+**II. Make illegal states unrepresentable.** The shape of a datum is
+its strongest invariant. Constructors refuse invalid states; a checked
+fact becomes a type; downstream never re-proves what upstream
+established. Parse, don't validate.
+
+*Functions — one idea, honestly declared*
+
+**III. A function is one idea.** It takes exactly what it needs and
+returns exactly what it computes. If the signature has two concepts in
+it, you have two functions.
+
+**IV. The signature tells the whole truth.** Inward: if something
+needs a value, it receives it as a parameter — no spooky action at a
+distance, no stringly-typed interfaces, no implicit state. Outward:
+same inputs, same outputs; effects and failure appear in the type, not
+in the fine print. Pure core, effects at the edges.
+
+*Knowledge — one home per fact*
+
+**V. Every fact has one home.** One authoritative representation of
+each decision and each piece of knowledge; everything else inherits or
+is derived mechanically — never maintained by hand in parallel.
+Configuration is decided once, at the highest level, and threaded
+down; no module ever decides its own context. If the design and the
+implementation can disagree, you have two sources of truth and zero.
+
+*Layers — what above, how below*
+
+**VI. Separate what from how.** Logic and machinery are different
+concerns with a hard boundary. The layer that says *what* to compute
+should be readable by someone who has never seen the machinery
+underneath. The layer that says *how* lives below, stays below, and
+nothing leaks up from it.
+
+**VII. Notation is execution; lowering is transliteration.** Looking
+up: the spec layer reads like the math or logic it implements — when
+notation *is* the executable object, not a comment beside it, bugs
+have nowhere to hide. Looking down: the layer that executes the spec
+reproduces it exactly — nothing added, nothing dropped, nothing
+reinterpreted; no opinions, no defaults, no helpful conversions. If
+the lowering changes anything, the spec is a lie.
+
+*Abstraction — earned, and binding*
+
+**VIII. Earn your abstractions.** No abstraction before the second
+use. Three similar lines is better than a premature helper. The right
+amount of complexity is the minimum the current task demands — not the
+current task plus three hypothetical future ones.
+
+**IX. An abstraction is a contract.** It is defined by what it
+guarantees, not what it hides. If you can't state what is always true
+of it — properties a client may rely on without reading the
+implementation — it isn't an abstraction, it's indirection. Two
+implementations that honor the contract must be interchangeable; and
+its outputs stay in its vocabulary, so uses compose.
+
+*Verification — formal first*
+
+**X. Trust the most formal thing first.** Types over tests, tests
+over docs, docs over comments. Invest in whichever layer catches the
+bug earliest with the least ongoing maintenance cost.

.agents/skills/postgkyl-development/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: postgkyl-development
+description: Set up Postgkyl development, choose verification commands, or maintain shared agent configuration and Entire hooks.
+---
+
+# Develop and verify
+
+Install NumPy before the extension so it builds against the runtime ABI:
+
+```bash
+pip install --upgrade numpy setuptools wheel
+pip install --no-build-isolation -e '.[test]'
+```
+
+Run focused tests for the change, then the required broader checks:
+
+```bash
+pytest tests/
+# Without an editable install:
+PYTHONPATH=src python -m pytest tests/
+```
+
+Useful API/CLI smoke checks (replace data filenames with suitable fixtures):
+
+```bash
+pgkyl --help
+pgkyl --version
+pgkyl file.gkyl info
+pgkyl file.gkyl interpolate select --z0 0 plot
+pgkyl euler_5m_0.gkyl interpolate five_moment_pressure --num_moms 5 plot
+pgkyl a.gkyl b.gkyl evaluate "f0 f1 +" interpolate plot
+```
+
+Shared agent configuration lives in `.agents/`; `.claude` and `.codex` are
+relative symlinks to it. Root `CLAUDE.md` links to `AGENTS.md`. Put focused skills
+in `.agents/skills/<name>/SKILL.md` with name and description frontmatter. Keep
+root instructions short and route only to skills relevant to the task.
+
+Preserve Entire's Claude hooks in `settings.json` and Codex hooks in `hooks.json`
+inside the shared directory, including matchers, commands, and timeouts. Their
+original `.claude/settings.json` and `.codex/hooks.json` paths must still resolve.
+Leave `.entire/` and Entire's Git hooks intact. Retain existing agent definitions
+and historical plans when reorganizing folders; historical markdown remains
+ignored, while new skill entry points must be visible to Git.
+
+For instruction/configuration-only changes, validate skill frontmatter, relative
+links, Git visibility, and hook preservation; running scientific tests is not
+necessary unless application behavior changes.

.agents/skills/postgkyl-native/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: postgkyl-native
+description: Change or troubleshoot the Gkeyll native bridge, basis matrices, readers, memory ownership, or native builds in Postgkyl.
+---
+
+# Keep the foreign boundary compiled
+
+`gpython/` is the only doorway to Gkeyll. No ctypes declarations, native struct
+layouts, or foreign signatures in Python or other layers. `gpython.available()`
+is the single capability switch.
+
+The shim lives in `gkeyll/core/zero/{gkyl_gpython.h,gpython.c}` and builds into
+Gkeyll's `libg0core.so`. Struct access, by-value basis conventions, and function
+pointer dispatch belong there, checked against that tree's headers.
+`gpython/csrc/_gpythonmodule.c` wraps only the shim's opaque handles, scalars,
+and buffers. `_lib.py` imports the extension and checks `GPYTHON_API_VERSION`.
+
+Build against the pinned clone using `scripts/build_gkeyll.sh` and
+`scripts/build_gpython.sh`. Bundle libg0core beside the extension and retain
+relative `$ORIGIN`/`@loader_path` linking. Preserve generated build provenance;
+Gkeyll is a build-time clone and need not exist at runtime.
+
+GkylArray capsules own and release arrays. Zero-copy construction pins its NumPy
+buffer; view base chains pin the capsule so views outlive their dataset. Never
+return unowned C memory. Build interpolation and representation matrices by
+evaluating Gkeyll's own basis through the shim, not duplicated basis formulas.
+
+`dg/` orchestrates kernels; `io/` dispatches readers. Prefer GkylCReader for native
+field reads; retain the Python reader fallback for unavailable native libraries,
+partial loads, and dynvectors. Keep NumPy installed before building so the
+extension uses the runtime ABI; use `pip install --no-build-isolation -e '.[test]'`.
+
+Verify handshake, memory lifetime, basis/interpolation, and modal algebra using
+the relevant existing tests. Report native test skips explicitly when no compiled
+library is available; skips do not establish native correctness.

.agents/skills/postgkyl-testing/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: postgkyl-testing
+description: Design and best practices for testing Postgkyl code, including unit tests and examples.
+---
+
+# Testing
+
+Unit tests aim for 100% code coverage where possible. Every change must have an associated unit test. Every bug fix must have a test. Every feature must be tested. Run `pytest` to check that all tests pass.
+
+Data for testing must be generated automatically by `tests/generate_test_data.py`. This keeps the repository light. DO NOT COMMIT LARGE DATA FILES TO GIT.
+
+Examples are real-world use cases of postgkyl. They read data and make plots. Examples are displayed in the documentation.

.clang-format

@@ -0,0 +1,21 @@
+---
+Language: Cpp
+BasedOnStyle: LLVM
+
+ColumnLimit: 80
+
+IndentWidth: 2
+ContinuationIndentWidth: 4
+TabWidth: 2
+UseTab: Never
+
+AlwaysBreakAfterReturnType: AllDefinitions
+BreakBeforeBraces: WebKit
+AllowShortFunctionsOnASingleLine: None
+
+DerivePointerAlignment: false
+PointerAlignment: Right
+
+IncludeBlocks: Preserve
+SortIncludes: CaseSensitive
+...

.claude

@@ -0,0 +1 @@
+.agents

.codex

@@ -0,0 +1 @@
+.agents

.github/dependabot.yml

@@ -0,0 +1,22 @@
+version: 2
+
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      python-dependencies:
+        patterns:
+          - "*"
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns:
+          - "*"
+    open-pull-requests-limit: 5