Margam repository instructions¶

Working location and environment¶

• Work in the Margam repository root. Do not put project code or documentation in a separate chat workspace, even if that is the chat's initial directory.
• Reuse the single repository-root .venv. Check its Python version and installed dependencies before changing it. Current development uses Python 3.14.
• Do not create virtual environments inside feature folders or invent additional environment/backup directories. A Python upgrade should be a deliberate, user-authorized change to the root environment.
• Use uv pip ... --python .venv/bin/python for dependency management. Do not assume the environment has its own pip module. Follow README.md for running commands.

Repository organisation¶

• Source: margam/; numerical methods: margam/methods/; shared components: margam/components/; configured examples: margam/templates/; desktop: margam/ui/.
• Keep one file per PINN recipe under margam/recipes/. That file defines its components, connections, defaults, ports and compact settings. Compact and expanded insertion must share that definition; physics examples stay separate.
• Keep one file per PINN method. Reuse shared sampling, optimisation, networks and loss components, while allowing a method to own its distinctive behaviour.
• Tests belong in tests/, runnable examples in examples/, documentation and plans in docs/, static resources in assets/, screenshots in assets/screenshots/. Keep the root limited to standard project metadata, instructions and setup files. Do not leave scratch code or images there.
• Keep implementation status, component capabilities and limitations documented. Update README.md running commands and docs/todo.md as work changes.

Scope and interaction design¶

• Build concrete supported workflows first. Do not invent generic registries, extension frameworks, universal plot actions or broad abstractions without a demonstrated need. Share actual common behaviour rather than hypothetical cases.
• Follow the documented Simulink interaction reference in docs/simulink-evidence.md, distinguishing verified behaviours from deliberate Margam choices.
• The project is a PINN builder across physics, not a heat-transfer-only tool. Keep demo-specific assumptions in templates rather than shared UI contracts.
• Basic interval/rectangle sampling must work directly. Advanced CAD/geometry workflows belong to future GeoSampler integration. Do not add a 3D viewport.
• Views are optional and owned by their blocks. Do not show global default figure panes or assume an analytical solution. Only expose supported context actions.
• Local sample/geometry previews currently belong to Rectangle blocks only. Keep operational progress/errors separate from numerical output views.
• Do not continue polishing or expanding in-app field heatmaps without a concrete user request. Preserve existing behaviour unless the user requests removal.
• ParaView file export was explicitly requested and is supported through its own opt-in block. Viewer embedding/launching and arbitrary mesh export remain deferred. Concrete 2D transient flow is supported by the Expert suite; do not infer generic 3D support.

Validation and commits¶

• Check the current branch and working tree before editing; preserve user changes.
• Keep dev untouched unless the user explicitly authorizes changes to it.
• Run checks appropriate to the change. Verify UI interactions and lifecycle where relevant; store screenshots under assets/screenshots. Label CPU-only validation and CUDA skips accurately. Do not claim numerical accuracy from UI startup alone.
• Make regular, coherent commits at verified milestones. Do not leave completed work uncommitted or push changes unless the user requests it.
• Every commit created or amended by Codex must include this exact trailer, separated from the commit body by a blank line:

Co-authored-by: Codex <codex@openai.com>

This includes documentation-only commits. Preserve the human author's identity. Do not rewrite existing history unless explicitly authorized for that purpose.

Current data and desktop contracts¶

• Core parameters are owned by blocks. Assemble supported physics through the typed graph; the inspector cache is not numerical source-of-truth.
• Keep restricted expressions interpreted through the allowlisted AST. Do not replace this with Python eval or executable model-file payloads.
• Run archives load with weights_only=True and verify architecture, Adam options and data fingerprints. Do not silently resume against changed external data.
• Unit tests must use Window(state_directory=False), or a dedicated temporary directory when testing desktop state. Do not overwrite personal layout/recovery files during validation. Release test clipboard data before offscreen Qt teardown.

• Coupled u/v/p results currently use tables/CSV. Preserve the pause on heatmap development. Full 3D/non-planar GeoSampler remains deferred. ParaView export is opt-in; never infer physical time from training updates. Evaluation points and Reference data blocks accept CSV/NPZ independently of training. Preserve exact coordinates, row order and integer/text IDs. Align references explicitly without interpolation. Supplied clouds export as VTU vertices and physical-time PVD; mesh connectivity, units/region metadata and GeoSampler integration remain deferred.

• Prepared 2D uses separate Interior data and Boundary data blocks, with coordinate bounds for scaling only. Keep free boundary labels and target/operator physics separate. Require explicit unit outward normals for normal-dependent conditions and explicit evaluation points; never fill an unknown domain with box samples. The current non-rectangular contract is steady planar scalar baseline/LRA/fixed-SA.

• Residual samplers own initial points and schedules; trainer hooks perform scoring. Preserve inverse-probability MSE for importance sampling and checkpoint the active set/history. Keep BCs/export grids separate. Reject SA masks and imported-domain candidate generation until their explicit data/transfer contracts are implemented.

• Integral loss integrates squared pointwise errors with physical measures; it does not square a signed residual integral. Keep mean MSE the default, sum vector components in integral mode, and retain unit endpoint/gauge penalties. Apply volume once with importance correction. Reject RAR/imported quadrature until appropriate point weights exist; persist mode/measures in checkpoints.

• Credit community implementation references in docs/community-methods.md and each method guide. Distinguish algorithm inspiration from copied/adapted source, retain exact upstream references/notices, and state implementation differences.

• Burgers uses explicit SpaceTime1D geometry and (x,t) coordinates, two spatial boundary traces plus an initial set; never impose a final-time BC. Keep its solution in the existing table view and export physical-time PVD line frames, not a VTI plane treating time as space. Do not assume an exact later-time reference.

• Expert PINN is Margam’s label for Expert’s Guide v1, not an author-proposed name or mixture of experts. Follow paper sum-L2-gradient-norm balancing and old-weight EMA; do not substitute existing max/mean LRA. Causal weights are detached and (x,t) pairs stay intact. Preserve same-device sampling/decay resume. The inspected JAX-PI licence restricts copying; use independent paper-based code.

User documentation¶

• Keep task-based help under docs/start, docs/modeling and docs/use, with docs/index.md as the user entry. Keep method/API/evidence pages separate as reference.
• Update screenshots/captions when their controls change; use the state-isolated examples.capture_manual helper, with images in assets/screenshots.
• Build/check with examples.documentation. Generated source/site stay under the ignored build/manual directory; never edit generated copies. Local builds do not publish. The dedicated Pages workflow deploys the manual when main is pushed; do not push or change remote Pages settings unless the user requests it.

• F1 opens the local built guide. Zensical is an optional docs extra, not a numerical or desktop startup dependency. Preserve offline assets and their licenses.

• Public documentation, snippets, screenshots and capture manifests must not contain local usernames or home-directory paths. Use repository-relative demo paths, and inspect capture inputs before saving screenshots. Keep real local filesystem paths confined to local tool operations and diagnostic UI when needed.

• Expert suite examples use concrete paper-case contracts. Torus Taylor–Green and cylinder startup are explicitly labelled variations. Preserve obstacle exclusion, outlet traction, cavity corner handling and physical-time PVD frames. Torus output w is scalar vorticity, not vertical velocity. Do not claim paper accuracy or Reynolds curriculum support. NTK and sequential time marching are opt-in Expert controls; preserve detached teacher ICs, per-window Adam/EMA resets, local coordinate bounds and piecewise physical-time predictions. Reject predictions beyond trained windows and validate the complete teacher/checkpoint chain.

• Scale-PINN is an independent paper-based trainer. Keep w^(k-1) frozen, compute its spatial derivatives before detaching the correction, and snapshot w^k before the optimizer step. Time is never a smoothing dimension. Flow correction maps velocity to momentum and pressure change to continuity; reject undefined mappings. Preserve both iterates in archives and distinguish physical PDE MSE from corrected training loss. The upstream repository declares all rights reserved; do not copy code/data.

• Scale high-Re cavity entries are independent starting presets, not solved benchmarks or a curriculum. Keep ν and default γ at 1/Re for unit lid speed/length and display Re from current parameters. KdV uses third-order dispersion and periodic matching through second derivative; KS fourth-order coefficient is 100/16⁴. Preserve physical-time exports and label borrowed tuning settings.

• Jorvik geometry documents are explicitly enabled for steady planar 2D scalar imported samples. Keep the editor in a separate process using the root environment. New documents use .jorvik; exports use domain.nc beside domain.jorvik. Export saved generated arrays automatically on editor close and Update, using Jorvik project validation and atomic export; never regenerate samples or silently fall back to stale exports. An explicitly browsed NetCDF copy overrides this. Prefill dataset roles from metadata and boundary names from labels; Ignore is opt-in. Apply updates explicitly with dataset-role review, stable region IDs, verified planar conormals and immutable owned snapshots. Never assign PDE/BC physics from labels or infer mesh topology. Preserve relative owned references, Save As isolation, owned-file recovery and the editor lock during save/close. Broader GeoSampler/3D integration remains deferred.

• New Scale examples use notebook-specific affine inputs and a trainable sine projection in the separate Affine Fourier NN architecture. Preserve physical units by default, keep normalization explicit, and do not silently migrate old fixed-Fourier checkpoints or claim upstream trunk/head equivalence.

• gPINN differentiates the full scalar residual including forcing/coordinate-callable targets, not its square or just the solution. Preserve higher-order parameter gradients. Keep coordinate penalties explicit; zero disables a direction. Log raw gradient terms separately, preserve BC/IC losses and score RAR on physical residuals. Mean/fixed/RAR only; do not silently compose advanced trainers.

• RBA uses detached normalized absolute PDE residuals and squared weighted residual losses. Keep point identities fixed, both initialization modes and zero-residual safety. Commit attention only after a successful update; checkpoint masks separately from optimizer parameters. Never silently move or interpolate attention under resampling. Keep raw and weighted PDE diagnostics distinct.

• PDE collocation follows point-source arrows. The optional boundary input adds geometric boundary/initial rows; without that wire do not append them. Allow a boundary source on the primary collocation input too. Keep BC operators separate. New example graphs wire both sources, while old documents/API defaults remain interior-only. Preserve duplicates, forcing derivatives, adaptive boundary anchors with unit importance weights, and physical-time causal bins. Reject extra boundary rows as domain-volume integral quadrature; never silently mix measures. Exclude pressure gauges and mean-velocity anchors from geometry rows.

• Desktop execution device is an application-wide preference (Automatic/CPU/CUDA), overriding legacy per-block values. Keep CLI options explicit and independent. Preserve trained weights on device changes; rebuild prediction weights on the chosen target when needed. Resume must honor the global selection. Data and UI preparation stay on CPU. Lock device changes during running jobs/editors.

• Inspector and library information buttons open scrollable descriptions with actual choices/limits. Reuse existing widgets; avoid inventing unsupported parameter semantics in fallback help.

• Add a dedicated setting-help description when introducing numerical controls; explain its meaning and interactions. Available choices and limits are read from the live widget, including disabled choices. Keep fallback descriptions limited to actual widget values and block capabilities.

• Run archive version 4 embeds project-owned files in a bounded, validated relative file map. Restore into a new private workspace before replacing the graph; preserve older archives and external-input semantics. Never extract traversal, absolute, ambiguous or conflicting paths, or follow symlinks when capturing.

• BC blocks own positive per-constraint bc_weights, default 1, multiplying the existing normalization/global weight without renormalization. Keep raw losses separate from weighted:<name> objective contributions. Record adaptive contributions using the weights actually used before the optimizer/mask update; never reconstruct older missing history from current coefficients. Model 27 migrates old BC blocks to defaults. Reject changed objectives on continuation and clear removed Jorvik aliases' coefficients alongside their physics settings.

• CSV/NPZ mapping dialogs offer explicit Copy into project / Link existing file. Default new sources to Copy, preserve existing links, and copy only after an accepted validated mapping. Validate copied bytes before installing references; retain fixed snapshots for undo and include them in existing recovery/run payloads. Canonicalize owned mapping paths in editor parameters and undo values. Resolve all training/evaluation/reference mappings at use; rebase cached trained configs across Save As without treating file relocation as changed physics. Never turn an owned URI into an absolute external link or silently bundle external files.

• Project data overview is a read-only inventory of block-held file mappings, including disconnected/unmapped source blocks. Inspection must not mutate model, undo/results or filesystem; Refresh must not replace established baselines. Use non-creating owned-path resolution for missing-file checks. Use saved accepted-import fingerprints when available, and label only older unrecorded mappings as session-only; use Jorvik's applied fingerprint where present. Mapping edits are explicit, guarded while busy/stale, and use the existing owning block's dialogs. Disconnect observers on window shutdown; do not retain stale Qt node references.

• Explicit desktop Validate opens a clickable multi-issue report; programmatic validation remains boolean and non-modal. Keep the supported numerical execution checks required; active data guards may reject cases older lazy reference callbacks deferred until prediction. Require explicit evaluation points on prepared-domain outputs, validate mapped legacy reference alignment before training, and resolve inputs without creating missing owned folders. Reuse actual expression/data/network/method validators; avoid a second numerical executor or promises of exhaustive diagnostics on incomplete graphs. Unused optional sources/outputs are advisory. Preserve model/history, files and results while inspecting; selecting an issue only opens its owner. Use IDs instead of retaining Qt nodes, guard stale boundary contexts, and disconnect report observers on window shutdown.

• Model 28 persists data_fingerprints separately from numerical mappings. Record them only on an explicitly accepted dataset mapping, bound to that exact mapping; never fabricate historical checksums or rebase them during inspection, validation, save or archive reopening. Keep mapping/fingerprint edits undoable together, and clear cached training weights when reaccepting training data. Valid changed imports are warnings for fresh training, while checkpoint data identity and Jorvik snapshot checks remain strict. Keep hashing bounded and metadata decoding independent of Qt.