Current TODO¶

See roadmap.md for the agreed design and stages. Completed historical DeepINN checkboxes are not claims about current Margam support.

Audit on 27 October 2026: the current implementation items below are addressed. The remaining unchecked entries are explicitly deferred scope or external validation prerequisites; they are not presented as completed work. Current execution is one supported problem root, not arbitrary multi-model simulation.

Menus and explicit outputs¶

Left library and sampling options¶

Replace the flat left-hand list with a searchable, collapsible component library: Geometry, Sampling, Neural networks, Loss / Physics, PINN recipes, Training, and Results. Template actions remain separate in File/the toolbar. Search matches block/category names and restores collapsed groups when cleared. Only implemented blocks are listed; Enter and double-click add a block.
Group sampling by purpose: interior/PDE points and boundary point sets. Within each, show implemented methods and their supported settings. Sampling method is distinct from the target region; assigning a BC is a later operation.
Keep basic built-in interval/rectangle sampling in Margam: grid and seeded uniform random, domain/side selection, point budget or points-per-side, seed, actual count and preview. A simple problem must not require GeoSampler.
Let the template interior and each named rectangle side use independent sampling recipes, methods, counts and seeds. Intervals retain fixed endpoints. Arbitrary additional sampler instances still depend on future graph execution work.
Share implemented block status, parameters, compatible ports and limits across the library, inspector and Help. Property sampler choices come from the implemented sampler catalogue. Keep widgets explicit; no generic plugin registry.
Define the GeoSampler ownership/import boundary in geosampler-contract.md; keep CAD authoring/selection outside Margam. The planar bridge is implemented.
Keep library, ports, conditions, data imports and output requests expressed as scalar fields/operators, independent of temperature. Heat remains a preset; vector/coupled schemas are an explicit future extension.

Simulink interaction evidence¶

Collect official, release-labelled documentation for library insertion, parameter editing, wiring, navigation, outputs, diagnostics and persistence. See simulink-evidence.md for sources, explicit Margam adaptations, implementation order and acceptance checks.
Add library drag/drop and searchable canvas quick insert, sharing the supported UI catalogue and existing block creation path. Placement respects pan/zoom; empty-canvas double-click and canvas-only Tab open quick insert. This does not generalise the template-backed core execution model.
Define contextual double-click behaviour: core/reference blocks use the shared inspector; output blocks open/reuse their owned views. No separate parameter-dialog state is introduced.
Store core parameters on their block instances, including independent network initialisation seeds; editing/copying one instance does not overwrite another.
Support output branching from one method/reference to distinct consumers, with one source per typed input and no implicit view creation.
Add undoable graph/parameter edits, including grouped drag moves, restored block IDs/settings/wires, per-editor value coalescing and a 100-command limit. Training locks history. Template changes start fresh; run data/views are excluded.
External prerequisite: validate interaction parity hands-on against a licensed Simulink session. No MATLAB executable was found on PATH on 27 October; current evidence and native Qt tests do not constitute a licensed live comparison.

Output/menu milestone (26 October 2026)¶

The first output-ownership stage in simulink-evidence.md is implemented and verified. See ui-prototype.md for actual menu actions, output lifecycle and limits. The searchable, collapsible library and independent rectangle-side sampling recipes are implemented. The component catalogue records implemented capabilities; supported catalogue descriptions are shared by the library, inspector and Help.

Block-owned rectangle previews and context menus¶

Add block-specific right-click menus for Properties, Delete and Help, plus only the view actions each supported block actually provides.
Remove the default domain/sample figure pane; keep operational Messages separate and initially hidden.
Add optional Rectangle → Preview geometry / Preview samples windows, floating by default and owned by that rectangle block.
Reuse hidden previews and update them on settings changes; remove them on owner deletion, shape change or template reset.
Keep these sample previews limited to rectangles. Do not create a general geometry renderer or implicit 3D preview path without a justified requirement.
Add Undo/Redo actions to block context menus.
Add undoable block Copy/Cut/Paste with fresh IDs, internal wires and canvas-scoped shortcuts. Pasted core settings remain template-backed.
Add pointer-centred wheel zoom, mouse/Space panning, zoom controls and fit-to-model.

Add a separately loadable steady heat demo with monitor, prediction, Reference and Comparison blocks fully connected.
Add a labelled rectangular sine-series reference and verify it against finite differences and increased truncation order.
Show 2D prediction/reference/error with shared prediction/reference colours, RMSE and maximum absolute error only when comparison is explicitly requested.
Quantify rectangular training error for three seeds and two soft BC weights, and add/verify an optional hard-Dirichlet method that improves field error in every tested seed. See heat-accuracy.md; no field plots were changed.

ParaView file export¶

Add a separate opt-in ParaView Export block for regular-grid predicted fields; retain CSV Export and never create files or launch viewers by default.
Write uniform-grid VTI scalar/u-v-p data and a derived velocity vector.
Support physical-time PVD collections and per-snapshot TimeValue metadata in the writer API, with a known-value playback dataset and real VTK reader checks.
Deferred: actual transient PINN solver/UI integration and physical-time selection.
Deferred: embedding/launching ParaView and direct viewer integration.

Future evaluation and export at supplied points¶

The first supplied-point milestone is implemented; see the illustrated guide.

Separate Evaluation points and Reference data blocks with explicit CSV/NPZ mapping, finite/domain checks, independent of training samples.
Predict at exact supplied coordinates, preserving row order, integer/text IDs and source fingerprints. No interpolation or automatic remeshing.
Align supplied reference fields by ID and coordinates (or unique coordinates), and export predictions, references and signed pointwise errors.
Reevaluate output-only changes with trained weights and no optimizer updates.
Export supplied points as VTU vertices; group transient rows into physical-time PVD frames, preserving IDs and original source-row indices.
Save results in run archives for offline viewing/export, add a wired example, CPU/CUDA evidence and actual UI screenshots.
Preserve mesh connectivity and node-versus-cell association when supplied; add an explicit topology contract rather than guessing cells from a point cloud.
Add explicit units, boundary/region labels and GeoSampler prepared-data integration. Coordinates/values currently use the model's units without conversion.
Add user-selected relative/vector error norms and zero-denominator rules. Current comparisons report scalar/component RMSE, maximum absolute error and signed pointwise differences.

Existing in-app heatmaps are left as they are. Further field-plot development is paused; operational training monitors and basic rectangle previews remain useful.

Add a toolbar/View Pan toggle with open/closed hand cursors and Escape to return to block selection. Existing temporary pan gestures remain supported.

Problem catalogue and PDE presets¶

Group all runnable desktop problem templates under File → Examples.
Retain editable PDE residual and add alternative Predefined PDE block.
Add manufactured interval Poisson, reaction–diffusion, advection–diffusion and 2D sine Poisson examples with explicit references.
Check manufactured equations, CPU training, graph assembly and model format.
Add palette-aware vector icons to the toolbar, menus and collapsible block library; retain labels and keep demo shortcuts in File → Examples.

PINN recipes¶

Define the baseline recipe in one file with shared components, exposed settings, ports and internal connections.
Insert compact or expanded; expand by double-click/context action and collapse a baseline trainer with its private network.
Preserve network/training parameters, external connections, history, clipboard and saved-model compatibility; verify actual training equivalence.

Self-adaptive PINN¶

Read the supplied McClenny/Braga-Neto paper and verify the pointwise mask objective and ascent/descent updates against primary sources.
Add a separate method and one-file compact/expanded SA recipe; fixed samples, squared mask, configurable ascent rate/initial weight/cap, optional adaptive BCs.
Add a runnable File → Examples problem, explicit weight summary, full adaptive checkpoint/resume, equation/gradient checks and an equal-budget CPU comparison.
Reproduce a stiff benchmark protocol from the paper before claiming an advantage there; L-BFGS and GP-resampled minibatches remain unsupported.

Documentation and evidence¶

Add a documentation index and results catalogue; separate measured studies, regression thresholds, historical records and unreproduced protocols.
Save the repeated SA comparison with settings, environment, source hashes, full-precision errors, final losses and weight summaries.
Preserve historical GPU metadata separately from current CPU validation.
Consolidate setup/run commands, update menu/persistence/recipe guidance, and document the concrete process for adding and recording a new method.

Pointwise networks¶

Inspect NVIDIA layers/full model equations; adapt angular/Fourier, highway, modified/multiscale Fourier, DGM, SIREN and Fourier/Gabor filter networks.
Add architecture controls to the shared network block and retain them in both recipe forms, model migrations, copy/undo and validated checkpoint resume.
Check first/second derivatives, physical scaling, batch independence, gating, original FCNN identity, real scalar/flow training and all-architecture archives.
Record a twenty-run CPU compatibility study with configs, predictions and provenance; retain Apache notices and keep neural operators out of scope.

Illustrated documentation¶

Add a coherent network/PINN screenshot walkthrough with native menus, architecture-specific settings, compact/expanded views and explicit losses and interval reference comparison; keep numerical evidence separate.
Provide repeatable state-isolated screenshot capture with a real CPU run, configuration assertions, source/settings manifest and no silent overwrites.

Learning-rate annealing PINN¶

Implement supplied Wang/Teng/Perdikaris v1 Algorithm 1 independently of its architecture.
Add one-file compact/expanded recipe, editable balance controls and optional summary.
Reuse all existing pointwise networks and scalar/coupled builders; validate checkpoint continuation.
Record equal-budget CPU baseline/LRA results including coefficient-cap sensitivity.
Deferred: reproduce a paper benchmark with its full sampling/training protocol; current small Poisson evidence is not that reproduction.
Separate PINN method, Optimisation and Trainer inspector groups in compact and expanded recipes; distinguish network Adam descent and SA mask Adam ascent.
Split library categories into PINN recipes (compact constructions) and Training (expanded trainers). Optimisation remains inspector settings until standalone blocks exist.
Group five 1D problems in File → Examples → 1D examples, with explicit 2D labels on the parent-menu cases.
Add the LRA paper 2D Helmholtz problem with existing Fourier features, explicit forcing/reference and soft BCs; verify desktop/persistence and record CPU results. Paper-architecture and full stochastic benchmark reproduction remain outside this example.

Future studies, iterator blocks and laptop/HPC sweeps¶

See study/sweep vision. These are proposed features; current execution still runs one supported problem.

User-friendly illustrated help¶

Add a searchable local manual with short task-based walkthroughs and separate reference/project sections, following the PyniteGUI documentation approach.
Capture 22 current Qt screenshots with captions and full-size links; verify a complete first-PINN workflow and preserve personal UI state during capture.
Add F1 / Help → User manual, with build guidance and clear browser errors.
Keep search/fonts local for offline reading; document optional build tools and verify rendered links, screenshots and help behaviour.
Add a GitHub Pages workflow that builds/checks and publishes the generated manual, with build-only PR validation and documented GitHub Actions source setting.

Residual-driven sampling (28 October 2026)¶

Integral loss formulation (28 October 2026)¶

Optional integral of squared PDE/BC errors using physical measures; preserve default mean MSE.
Correct component sums, importance correction, endpoint/gauge counting measure and method integration.
Trainer/compact controls, version migration, measure-aware checkpoint verification and UI tests.
Document NVIDIA pointwise-integral distinction, screenshot and non-unit-domain CPU evidence.
Imported quadrature weights and physical measures for GeoSampler point sets.
Integral constraints on quantities such as total flow/flux, separate from squared-error integration.

Burgers initial-value problem (28 October 2026)¶

Original 1D viscous Burgers PDE, viscosity and sine IC/zero endpoint setup.
Explicit x/t coordinate contract and 1D space–time geometry; no final-time BC.
Existing BC sampler handles two spatial traces and a named initial loss.
File → Examples → 1D examples, current networks and baseline/SA/LRA support.
Optional x/t/u table and CSV; ParaView block emits physical-time PVD line frames.
Model/run persistence, residual/IC/export tests, CPU evidence and screenshots.
Optional benchmark reference dataset/solver validation of the shock profile.
Additional transient PDE cases and higher-dimensional space–time domains require explicit use cases.

Expert’s Guide recipe (28 October 2026)¶

Scale-PINN core method¶

Independently implement sequential correction with frozen previous optimizer weights and spatial-only smoothing.
Explicit pressure-change correction for standard u/v/p continuity; reject undefined auxiliary-vorticity mappings.
One recipe file, compact/expanded forms, separate trainer controls and Allen–Cahn/cavity starter submenu.
Save/resume both network iterates and sampling phase; separate physical/corrected diagnostics and CPU/CUDA evidence.
Scale cavity starting presets at Re=400, 3200, 7500, 10,000 and 20,000, plus KS and periodic KdV; distinguish configured physics from reproduced accuracy.
Consider paper-specific architecture/frequency annealing separately; current method scope does not claim it.
Add Gray–Scott concentrations and Rayleigh–Bénard temperature/initial-data contracts before their Scale examples. Resolve the omitted buoyancy term in printed equation (26c) against governing equation (25c) and the physical reference before implementation.
GeoSampler-compatible boundary/geometry contracts for NACA0012 and three square obstacles; do not substitute a rectangular fluid domain.
Define composition contracts before combining Scale with Expert time windows, adaptive samplers or imported geometry.

Prepared training-data blocks¶

Add separate Interior data and Boundary data blocks, preserving old inspector imports.
Add Prepared 2D coordinate bounds and arbitrary named scalar boundary sets, with optional mapped targets/normals and downstream Dirichlet/Neumann/Custom assignment.
Reject missing/out-of-bounds data, missing required normals, conflicting targets, unsupported samplers/transforms and implicit bounding-box evaluation grids.
Add a mixed-BC triangle example, CPU/CUDA continuation/export evidence, actual UI screenshots and the illustrated guide.
Extend prepared geometry to concrete coupled/transient use cases when their point-set, gauge and initial/boundary contracts are specified.
Wire prepared GeoSampler manifests into graphs automatically; preserve mesh connectivity, units and region metadata through an explicit contract.

Affine Fourier mapping¶

Add a separate Affine Fourier NN architecture with restricted affine input expressions, optional normalization, learned projection/bias and sine scale.
Select notebook-specific cavity, Allen–Cahn, KdV and KS input maps in Scale examples; preserve existing saved fixed-Fourier networks without migration.
Check physical derivatives, trainable projection, checkpoint compatibility, recipe/UI persistence and short CPU/CUDA continuation; document architecture differences.

GeoSampler integration is on hold while its author improves it. Resume that work only when the user explicitly requests including it here.

Gradient-enhanced PINN¶

Implement scalar gPINN full-residual coordinate-gradient losses, including forcing/target derivatives, independently from Yu et al.
Add one-file recipe, compact/expanded trainer, per-coordinate weights, gradient monitor terms and strict checkpoint/model persistence.
Add 2D Poisson sine variation, Burgers and Burgers+RAR examples; verify CPU/CUDA derivatives, exact same-device resume, UI/export and document differences.
Consider coupled/vector residual-gradient aggregation against a concrete case.
Define independent gradient sample sets, inverse unknown parameters and integral/importance combinations before exposing those options.

Residual-based attention PINN¶

Implement detached residual-history recurrence and squared weighted PDE loss, both notebook initialization modes, zero-residual safety and no second optimizer.
Add one-file recipe, separate trainer, raw/weighted curves and attention statistics.
Preserve point identity and mask state through archives; verify CPU/GPU continuation, CPU loading of GPU archives, corrupt-mask guards and older methods.
Add Allen–Cahn and 2D Helmholtz examples, actual screenshots and recorded checks.
Define mask transfer before permitting resampling/minibatches, coupled residual attention, or dedicated training-point mask export/visualization.

Jorvik project documents¶

Portable imported datasets¶

Copy/link choice for CSV/NPZ training, evaluation and reference inputs.
Bounded validated snapshots with relative owned references; preserve existing links.
Save As and undo references remain portable; retain trained weights across relocation.
Recovery, moved models and independent run archives exercised on CPU and CUDA.
Prune unused owned dataset snapshots when their undo/history references are no longer needed.

Project data overview¶

View-menu inventory of imported interior, boundary, evaluation and reference data.
Ownership, row counts, mapping details and missing/invalid/changed warnings.
Select owning block/boundary and use existing mapping or Jorvik review actions.
Read-only checks preserve model/results/history and do not recreate missing owned folders.
Persist fingerprints when mappings are explicitly accepted; detect changed files across project sessions. Keep older unrecorded inputs labelled session-only.

Actionable model validation¶

Collect independent connection, network, PDE/BC, compatibility and input-data issues.
Click issues to select their owning block and boundary set; recheck after edits.
Distinguish blocking execution errors from unused optional declaration warnings.
Retain the authoritative numerical gate and avoid automatic repairs or training.
Cover missing normals, coupled-flow expressions, multiple missing files and stale/deleted owners.