Skip to content

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.

  • Catalogue implemented methods, sampling and optimisation components with API/UI support and limitations in components.md.
  • Reuse GeoSampler Hammersley and recursive stratified unit-domain samplers, with exact counts, seeded shifts/strata and physical interval/rectangle bounds. Existing grid/random sequences are preserved; SciPy-only methods are not exposed.
  • Add built-in intervals, squares and rectangles with grid/random meshless sampling.
  • Create named rectangle-side point sets, then assign constant Dirichlet/Neumann BCs.
  • Connect PDE points to the Poisson residual preset; defer additional pointwise inputs.
  • Expose restricted scalar PDE expressions in the UI, as selected by the user. Coordinates, u, c, arithmetic, derivatives and basic functions are supported.
  • Extend the field contract for the user-selected steady 2D incompressible case: u/v/p, editable momentum/continuity residuals, component BCs, pressure gauge, explicit references, table views and multi-column CSV/run persistence.
  • Add constant Dirichlet/Neumann settings, analytical normals and an explicit rectangle corner policy.
  • Add restricted custom scalar BC operators (including Robin expressions) and coordinate-dependent targets. Retain a Dirichlet anchor requirement.
  • Add CSV/NPZ point adapters with explicit coordinate, unit-normal and scalar value mappings and row previews. Interior imports are coordinates only; imported boundary normals/targets are supported. NetCDF/other formats need adapters.
  • Define typed editor ports and reject incompatible/occupied inputs before adding wires. Validate stored wire endpoints again before training.
  • Define executable scalar graph semantics: follow one PINN root's typed residual/BC/network dependencies, require a common geometry source and assemble the training recipe from owned block parameters rather than the inspector cache. Multiple roots/coupled systems remain an explicit future extension.
  • Add block/wire deletion and fit-to-model navigation.
  • Add versioned model Save / Save As / Open, including graph/configuration, block IDs/settings/positions, named sampling recipes, atomic replacement, validated loading, dirty state and Save/Discard/Cancel protection.
  • Add explicit saved-run archives with model definitions, requested predictions, monitor records, network/Adam state, validated CPU loading and resume updates. Model JSON files remain definitions only; run archives use .margam-run.pt.
  • Add bounded model undo/redo for add/move/connect/delete and settings.
  • Connect the baseline engine through background training with progress and cancellation.
  • Add a runnable Poisson visual template and verify the analytical interval solution.
  • Reuse GeoSampler-style Qt layout/settings and per-session lock-file recovery patterns. Save core dock layout/theme/library groups; recover unsaved model drafts without reopening plot views or loading numerical state.
  • Add an explicit planar GeoSampler schema-v2 NPZ bridge with label/axis selection, source provenance, unit-normal checks and no CAD runtime/viewport.
  • Deferred: full 3D/non-planar GeoSampler integration and richer region schemas.
  • External prerequisite: validate GPU training when a working NVIDIA driver and CUDA-enabled PyTorch build are available. Audit on 27 October: installed torch 2.14.1+cpu, torch.version.cuda=None, CUDA unavailable; nvidia-smi cannot communicate with the driver. CPU checks do not satisfy this item.
  • Add File / Edit / View / Run / Help menus for implemented actions. File offers model Open/Save/Save As, template actions and Quit.
  • Allow training without any plot/results block.
  • Make loss plots and prediction plots explicit optional output blocks, with per-instance history/evaluation settings.
  • Create/show output views only when explicitly opened through their blocks. Unconnected blocks can show a placeholder; only connected outputs request data.
  • Separate reference sources and comparisons from ordinary predictions; the current sources cover analytical intervals and equal-Dirichlet rectangular truncated-series references.
  • Remove automatic analytical-reference construction from the generic worker.
  • Keep operational status, progress, validation and failures available without numerical output blocks.
  • Add Training Monitor blocks with bounded recorded histories.
  • Support bottom docking, floating, hide/reopen, and removal with the owning block. Keep view visibility separate from data retention.
  • Add explicit imported scalar reference data and restricted reference expressions; matching evaluation coordinates required, no implicit interpolation.
  • Add a dedicated scalar/u-v-p CSV Export request block; files are written only on explicit export after training. The separate opt-in ParaView Export block now supports regular-grid VTI output; richer integration remains deferred.

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.
  • 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.

Heat demo and navigation milestone

  • 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.

Supplied evaluation and export

The separate Evaluation points and Reference data blocks now implement CSV/NPZ coordinate/ID imports, reference alignment and pointwise errors, without changing training samples. Supplied points use VTU vertices and physical-time PVD frames. Mesh connectivity, unit/region metadata and direct GeoSampler integration remain tracked in TODO.

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.

  • Define a saved study containing alternative PINN recipes/components and parameter choices, with inspectable resolved configurations for every trial.
  • Design iterator/alternative blocks for concrete existing components. Make Cartesian, paired and conditional combination rules explicit; preview trial counts and budgets before running.
  • Preflight each trial's component/parameter/data compatibility. Record skipped combinations and reasons in a dedicated study output; continue valid trials. Distinguish incompatible, invalid, failed, interrupted, pruned and completed outcomes. Never fabricate objective values for non-running combinations.
  • Add a shared GUI-independent execution entry point, so identical study/model definitions run from the laptop GUI or a headless command on an HPC node.
  • Persist stable trial IDs, full resolved settings, seeds, code/data provenance, resource settings, status/reason, logs, requested metrics, exports and checkpoints. Keep evaluation data and comparison protocols explicit across trials.
  • Add bounded local CPU/GPU scheduling, cancellation and checkpoint-safe resume; isolate failures and outputs so one trial cannot overwrite or corrupt another.
  • Add Slurm sbatch study export/execution and result collection, including explicit resource requests, input/artifact locations, optional job arrays, preemption/restart handling and reopening results in the GUI.
  • Assess Hydra, Optuna and W&B sweep integrations against the study contract. Keep configuration, search, execution and tracking separable; select tools later. Preserve offline operation and avoid mandatory tracking-service credentials.
  • Add correctness tests for expansion, conditional settings, compatibility reports, failure isolation, repeatability, resume and desktop/headless parity before pursuing sweep-driven solution accuracy.

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)

  • Separate RAR and residual importance sampler blocks; keep fixed sampling default.
  • Scheduled, seeded candidate scoring with derivatives and bounded scoring chunks.
  • Capped duplicate-free RAR additions; fixed-budget importance draws with inverse-probability MSE.
  • Baseline, hard-BC and LRA integration; fixed BCs and independent output evaluation.
  • Model migration, active-point/weight history checkpointing and exact resume tests.
  • Document formulas, DeepXDE differences, screenshots and CPU workflow evidence.
  • GeoSampler-provided admissible candidate sets for imported/non-box geometries.
  • Define SA-PINN mask and Adam-moment transfer before combining it with moving points.
  • Consider a sampler-owned live point-set view when there is a concrete need.

  • Revisit XPINN after a practical GeoSampler subdomain/interface sampling workflow exists.

  • Cross-check importance loss correction against NVIDIA Sym's area/density convention for equal-weight pools, including non-unit volume and gradients.

  • Consider field-gradient importance measures and fixed candidate pools as explicit options; retain residual sampling semantics for existing saved models.

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)

  • Define Expert PINN as Margam’s label for the paper v1 pipeline; document JAX differences and independent implementation.
  • Reusable exponential random weight factorization for MLP/Fourier/modified Fourier networks.
  • Detached causal time-stratum weighting, sum-L2-gradient-norm EMA groups and Adam exponential decay.
  • Fresh seeded random interior/BC/initial batches, temporal stratification and exact checkpoint continuation.
  • One-file compact/expanded recipe, Burgers example, controls and block-owned diagnostics.
  • CPU/CUDA formulas/archive/UI checks, screenshots and reproducible short-run evidence.
  • NTK-diagonal alternative balancing, verified against explicit parameter Jacobians; configurable sampled-row trace estimates.
  • Sequential time marching with frozen final-prediction transfer, per-window optimiser resets, piecewise outputs and archive resume.
  • Explicit composition of causal strata with residual-adaptive sampling/imported candidate sets.
  • Seven concrete Expert paper examples: scalar periodic problems, steady flow, torus and transient cylinder; labelled self-contained IC variations, dedicated submenu and physical-time exports.
  • Optional time marching for Expert transient examples; defaults retain a single window.
  • Reynolds curriculum and grid/parameter sweeps are outside the requested paper scope.

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.

Scale notebook input mapping

The separate Affine Fourier NN independently implements observed affine input equations and trainable sine projections from SCALE-PINN notebooks. Source hashes, exact mappings and architecture differences are recorded in the Scale guide. No upstream code/data was copied; the shared trunk is Margam's existing implementation.

Gradient-enhanced PINN (gPINN)

Implemented independently from Yu, Lu, Meng and Karniadakis (CMA 393, 114823, 2022), paper, authors' Apache-2.0 repository. The additional losses differentiate the full scalar residual in coordinate directions. Source hashes, scope and deliberate example differences are in the guide. No upstream code, datasets, TensorFlow or DeepXDE dependency is bundled.

Residual-based attention PINN

Implemented independently from Anagnostopoulos, Toscano, Stergiopulos and Karniadakis, CMA 421, 116805 (2024). The authors' MIT repository verifies the detached recurrence, squared weighted residual and initialization modes. Source hashes and differences are in the RBA guide. No upstream code or data is bundled. This is pointwise weighting, not Transformer attention.