Add a Warp (NVIDIA warp-lang) GPU backend for PySPH WCSPH

.ai/AGENTS.md

@@ -0,0 +1,9 @@
+# Agent Router
+
+This repository uses implementation-scoped memory under `.ai/implementations/`.
+
+## Active Implementations
+
+- `blast-from-the-past`: read `.ai/implementations/blast-from-the-past/AGENTS.md`, then follow that implementation's boot sequence.
+
+Do not put implementation plans, decisions, reviews, closeouts, references, experiments, or aspect notes at the top level of `.ai/`.

.ai/README.md

@@ -0,0 +1,9 @@
+# .ai/ - Implementation Memories
+
+This directory contains implementation-scoped AI memory systems.
+
+## Implementations
+
+- `implementations/blast-from-the-past/` - NVIDIA Warp exploration for PySPH GPU particle dynamics.
+
+Each implementation owns its own plans, decisions, ADR graph, reviews, updates, aspects, references, experiments, templates, scripts, and skills.

.ai/implementations/blast-from-the-past/AGENTS.md

@@ -0,0 +1,117 @@
+# Agent Operating Contract - blast-from-the-past
+
+This implementation directory is the memory system for one implementation - **blast-from-the-past** - being developed inside the PySPH host project. It is not a memory system for the host. When this implementation ships, this implementation memory is archived into permanent docs, not deleted.
+
+## Boot Sequence
+
+1. Read `.ai/implementations/blast-from-the-past/current.md`.
+2. If `current.md` lists in-flight experiments, inspect their actual outputs/logs and update each experiment's `status` and `last_checked` before doing anything else.
+3. Read `.ai/implementations/blast-from-the-past/implementation.md`.
+4. Read `.ai/implementations/blast-from-the-past/host-project-notes.md`.
+5. Read the most recent daily closeout. On the first session of a new week, also read the most recent weekly closeout.
+6. Identify which aspects today's task touches. Read those aspects' `context.md`, `open-questions.md`, `known-issues.md`, and only ADRs scoped to those aspects plus `global` via `.ai/implementations/blast-from-the-past/decisions/index.json`.
+7. Open or create today's session log and maintain its `memory_consulted` list as `.ai/` files are opened.
+
+State in chat that boot is complete before doing implementation work.
+
+## Authority Order
+
+1. Host project's pre-existing AI configs and conventions. No such configs were found during scaffold discovery; if added later, they override `.ai/`.
+2. `.ai/implementations/blast-from-the-past/aspects/<aspect>/context.md` for aspect-scoped matters.
+3. `.ai/implementations/blast-from-the-past/implementation.md` and `.ai/implementations/blast-from-the-past/conventions.md` for implementation-wide matters.
+4. `.ai/implementations/blast-from-the-past/skills/*.md` for procedures.
+5. Agent judgment.
+
+If `.ai/` content contradicts a host config, the host wins; flag it and propose an ADR. If two `.ai/` files contradict each other, the most recently dated artifact wins; flag and repair stale memory in the same session.
+
+## Five Non-Negotiable Rules
+
+### Rule 1 - Closeouts Are Tagged by User
+
+Every daily closeout, weekly closeout, and session log must begin with frontmatter containing a valid `user:` from:
+
+- `@kunalpuri-prediqt`
+
+The validator enforces this.
+
+### Rule 2 - Plan Before Code, Sign-Off Required
+
+Tier 0 trivial work: at most five lines, one file, no behavioral effect. No plan file; note it in the session log.
+
+Tier 1 lightweight work: single session, roughly 50 LOC, at most three files, no ADR-worthy decision, within boundary. Post a one-paragraph plan in chat, wait for approval, and quote the user's approval verbatim with timestamp in the session log.
+
+Tier 2 full work: write `.ai/implementations/blast-from-the-past/plans/{YYYY-MM-DD}_{slug}.md`, list aspects and host files, post it in chat, wait for `APPROVED`, `APPROVED WITH EDITS: ...`, or `REJECTED: ...`, and quote the approval verbatim in the plan.
+
+Approval integrity: never paraphrase approval. An approval the agent cannot quote did not happen.
+
+Experiments vs plans: parameter-only or config-only runs need an experiment entry. Persistent code changes need a plan.
+
+Boundary visibility: if a Tier 2 plan touches host files outside `.ai/implementations/blast-from-the-past/implementation.md`, set `within_boundary: false` and call it out. Approved out-of-boundary work must amend the boundary during review.
+
+### Rule 3 - Decisions Are Recorded as a Graph
+
+For non-trivial design/modeling choices:
+
+1. Create an ADR with `.ai/implementations/blast-from-the-past/scripts/new-decision.py`.
+2. Run `python .ai/implementations/blast-from-the-past/scripts/update-decision-graph.py`.
+3. Reference the ADR in plans, reviews, and session logs.
+
+ADR frontmatter is the single source of truth. Do not hand-edit `.ai/implementations/blast-from-the-past/decisions/index.json` or `.ai/implementations/blast-from-the-past/decisions/graph.md`.
+
+### Rule 4 - Review Before Commit; Owner Exception for Prototypes
+
+Before any commit:
+
+1. Produce a review artifact in `.ai/implementations/blast-from-the-past/reviews/`.
+2. Include diff summary, aspects, host files, behavioral/numerical changes, raw validation output, `validate-memory.py` output, risks, unresolved questions, and at least one visual aid or a one-line waiver.
+3. Post the review in chat.
+4. Choose and record one review mode:
+   - **Promotion review (default):** wait for `@prabhu` to reply `LGTM` and
+     quote the verdict verbatim in the review.
+   - **Prototype-owner review:** `@kunalpuri-prediqt` may explicitly authorize
+     the commit without external `LGTM`; quote that authorization verbatim in
+     the review and set `status: prototype-approved`.
+5. Only then commit. The commit message references the review and touched ADRs.
+
+The prototype-owner exception is narrow. Every condition below must hold:
+
+- the work is exploratory/prototype work inside the approved implementation
+  boundary: `.ai/` memory, experiments, `pysph/base/warp_*.py`, and focused
+  `pysph/base/tests/test_warp_*.py` files;
+- the approved plan is recorded when Rule 2 requires one;
+- the change does not alter generic public API/ABI, non-Warp host behavior,
+  dependencies/build/release configuration, or files outside the boundary;
+- the review clearly labels unvalidated behavior, incomplete phases, and
+  performance claims as prototype evidence rather than production results;
+- the commit subject begins with `prototype:`.
+
+Prototype-owner approval is not promotion approval. A cumulative promotion
+review with exact `@prabhu: LGTM` is still required before any prototype change
+is pushed to an upstream PR, merged into a production/release branch, presented
+as completed production work, or used to amend generic host interfaces. If
+scope crosses a condition above, stop and use the promotion-review path before
+committing the expanded change.
+
+### Rule 5 - Do Not Cut Long-Running Tasks Short
+
+For long tasks, proceed to completion or a defined checkpoint. Long numerical runs are handed off through experiment entries with `status: running`. If context is the genuine limit, write a session log with exact file:line, current test/experiment state, and the next concrete action.
+
+## Closing Every Session
+
+1. Finalize the session log with complete `memory_consulted`.
+2. Update today's daily closeout.
+3. Regenerate `.ai/implementations/blast-from-the-past/current.md` as a slim pointer.
+4. Update aspect questions/issues and experiment statuses.
+5. If it is Friday or the user says "wrap the week", produce the weekly closeout and run compaction.
+
+## Curation
+
+Weekly: run `python .ai/implementations/blast-from-the-past/scripts/compact.py`; daily closeouts and session logs older than 12 weeks move to `.ai/implementations/blast-from-the-past/updates/archive/`. Weeklies are never archived.
+
+Monthly: refresh active aspect `## Current understanding` sections and bump `last_reviewed`.
+
+Pruning signal: files absent from every `memory_consulted` for four or more weeks are pruning candidates.
+
+## Secrets
+
+Never copy credentials, tokens, API keys, connection strings, or private keys into `.ai/`. Reference locations by path only. `validate-memory.py` fails on detected secret patterns.

.ai/implementations/blast-from-the-past/README.md

@@ -0,0 +1,27 @@
+# .ai/ - Memory for blast-from-the-past
+
+Tracks the development of one implementation - **blast-from-the-past** - added to this repository. Additive: nothing outside `.ai/` changed at install except this repository's permitted root pointer and the permitted pre-commit hook.
+
+## For Humans
+
+- `implementation.md` - central spec, including the integration boundary and amendments log.
+- `AGENTS.md` - operating contract every agent follows.
+- `current.md` - slim live status, regenerated every closeout.
+- `aspects/<name>/` - context, open questions, issues, and notes for each dimension of the work.
+- `decisions/graph.md` - generated from ADR frontmatter; never hand-edit it or `index.json`.
+- `experiments/` - tracked runs, baselines, and validation studies.
+- `references/` - annotated literature, human guidance, and API references.
+
+## Validation
+
+Run:
+
+```bash
+python .ai/implementations/blast-from-the-past/scripts/validate-memory.py
+```
+
+The same command runs from the installed pre-commit hook.
+
+## When This Implementation Is Done
+
+Archive `.ai/implementations/blast-from-the-past/` into the host's permanent docs or under the implementation's directory. Do not delete it: the decision graph and validation history are part of the artifact.

.ai/implementations/blast-from-the-past/aspects/cython-boundary/context.md

@@ -0,0 +1,38 @@
+---
+aspect: cython-boundary
+implementation: blast-from-the-past
+owner: @kunalpuri-prediqt
+created: 2026-06-15T07:19:08 CET
+last_reviewed: 2026-06-15T08:34:00 CET
+status: active
+---
+
+# Aspect: cython-boundary
+
+## What this aspect covers
+
+What remains in `.pxd/.pyx`, what can be wrapped or bypassed, and how to preserve Cython ABI/API expectations while experimenting with Warp.
+
+## Current understanding
+
+ParticleArray is a Cython extension type declared in `pysph/base/particle_array.pxd`, and existing code can rely on cpdef/cdef methods plus `BaseArray` returns from `get_carray()`. The first Warp migration should preserve the existing ParticleArray public API and host carray compatibility unless a separate boundary amendment approves broader ABI/API changes.
+
+## Key sub-topics
+
+- `.pxd` declaration compatibility.
+- Cython extension build constraints.
+- Host boundary amendments.
+- Compatibility with `BaseArray`/NumPy readback paths.
+
+## References for this aspect
+
+- `.ai/implementations/blast-from-the-past/references/index.md`
+
+## Decisions affecting this aspect
+
+- Filter `.ai/implementations/blast-from-the-past/decisions/index.json` for `scope: cython-boundary` and `scope: global`.
+
+## Cross-aspect dependencies
+
+- Depends on: `host-integration` - build/test constraints.
+- Influences: all host code changes.

.ai/implementations/blast-from-the-past/aspects/cython-boundary/known-issues.md

@@ -0,0 +1,3 @@
+# Known Issues - cython-boundary
+
+- (none yet)

.ai/implementations/blast-from-the-past/aspects/cython-boundary/open-questions.md

@@ -0,0 +1,4 @@
+# Open Questions - cython-boundary
+
+- [open] Which `.pxd` declarations are stable public contracts versus internal implementation details?
+- [open] What level of ABI compatibility must be maintained for downstream users?