TensorPhysics

Tensor ecosystem vision and boundary contract: AI-era ecosystem vision. Read this before adding cross-project features. Project charter: TensorPhysics — scientific domain charter — ownership, non-goals, integration contract, and quality gates.

TensorPhysics is the scientific workflow, solver-coordination, and validation layer for the Tensor ecosystem.

System-wide entry point: Tensor Ecosystem System Overview — architecture, repository boundaries, shared contracts, end-to-end lifecycle, icebreaker application roadmap, and evidence/maturity rules.

Its goal is to let authorized agents drive the complete lifecycle—from engineering problem definition and solver selection, through reproducible HPC execution and data production, to dataset creation, AI/ROM training and evaluation, and delivery of engineering applications. TensorLBM, TensorFEM, TensorDEM, and TensorFVM remain independent specialist solvers; TensorPhysics provides the contracts, execution control, provenance, and validation workflow around them.

Mission: Agent-first lights-out science factory

TensorPhysics is the scientific execution and control plane for a persistent research environment in which authorized Agents can plan experiments, invoke scientific tools, inspect diagnostics, trigger independent validation, and choose evidence-backed next steps. Humans define goals, budgets, constraints, and approval boundaries; the system makes each permitted experiment reproducible, observable, and auditable.

It is not merely a chatbot wrapper around solvers. Its job is to turn an Agent's proposed research plan into a typed, bounded, traceable workflow and return evidence—not just a success message or a plausible explanation. Agent-generated results must pass independent checks before being promoted as validated evidence.

Runnable remote research loop: TensorDEM → S3 artifacts → TensorPlatform registration and retrieval.

Canonical architecture: Science Factory Architecture · System Overview

Role in the Tensor ecosystem

TensorPhysics is the scientific workflow and multiphysics coordination layer between an Agent/application and the specialist solvers. It turns approved plans into traceable execution: solver selection and lifecycle, dependency ordering, field exchange, checkpoints, run manifests, artifacts, diagnostics, and numerical acceptance gates.

• TensorPlatform supplies shared identity, data/experiment/model lifecycle, and governance services.
• TensorLBM / TensorFVM / TensorFEM / TensorDEM remain independent specialist solvers; TensorPhysics must not reimplement their numerical kernels.
• Agent tools should call typed, permissioned workflow operations and durable job/artifact identifiers rather than rely on unrestricted shell execution.
• HPC backends are execution targets behind adapters; orchestration contracts should remain backend-neutral.

The intended loop is goal and constraints → workflow plan → solver execution and field exchange → validation and provenance → dataset curation → model training/evaluation → engineering decision. Physical correctness must be established by solver-specific verification, conservation checks, sensitivity studies, and appropriate experimental or reference data—not by successful task completion alone.

Maturity note: the current implementation below lists concrete code-level capabilities. Coupling fixtures are contract tests unless explicitly qualified otherwise; checkpoint envelopes do not imply full solver restart/resume; and production cluster execution, complete adapters, and a validated icebreaking model remain separate milestones.

Current implementation

The main branch contains:

• A deterministic solver lifecycle scheduler with explicit physical-completion and step-limit states.
• Backend-neutral field descriptors and an in-memory field store with producer ownership, shape checks, timestamps, freshness limits, bounded history, and bracketed linear time interpolation (no extrapolation).
• Explicit PRE_STEP, AFTER_SOLVER, and POST_STEP coupling phases with stable callback ordering.
• A two-reservoir coupling test that checks total-mass conservation and same-step field delivery.
• A versioned JSON checkpoint envelope with atomic local-file writes and schema/clock validation.
• An implementation-level cross-solver fracture handoff (src/tensorphysics/failure_handoff/): the failure_faces interface is frozen at v3.0.0 as a sealed JSON packet with per-face geometry, mixed-mode fracture energy and a SHA-256 seal; a Hex8 FEM fracture-face extractor (Benzeggagh-Kenane mixed-mode toughness, strength criterion, crack-front polyline) feeds a DEM fragment consumer that re-derives areas from the vertex data, initialises polyhedral/clump fragments with the inherited fracture energy, and enforces area (≤1 %), energy (≤2 %), mass and clump-volume conservation gates. End-to-end case: notched three-point bend → failure_faces.json → fragments → free fall + impact, with the energy chain closing to 5e-14 relative. Report: docs/reports/p154w2_n03/REPORT.md.
• An ice-structure domain module (src/tensorphysics/ice/): adfreeze (freeze-bond) shear-strength model calibrated on the Frederking (1984) four-temperature data (max residual 3.3 %, < 15 % acceptance), Stefan-problem contact-time kinetics, three bond-degradation mechanisms (mechanical peel with a cohesive law, thermal melting, brine/salinity), and a beset-vessel breakout criterion F = tau*A_contact + mu*p_n*A_contact compared against bollard thrust for three vessel classes. Report: docs/reports/m789/w3n02_adfreeze_bond_report.md, artifacts: artifacts/adfreeze_bond/, tests: tests/test_ice_adfreeze.py. Evidence grade: REAL (no mock/stub paths).
• Initial RunManifest and ArtifactRef contracts with canonical config hashing, code-revision provenance, artifact checksums, resource/environment metadata, and explicit validation status.
• An optional TensorDEM 2-D adapter with integer-ratio subcycling, per-substep load callbacks, and strict clock checks.
• Structured diagnostics, a minimal runnable example, and a Python 3.10–3.12 GitHub Actions test matrix.
• An ice-induced vibration analysis module (src/tensorphysics/ice_vibration/): modal ice-structure coupled vibration, frequency lock-in criterion (5 % band, amplification factor), self-excited velocity-weakening lock-in, Duffing harmonic balance, and transient whiplash response of the first two hull-girder bending modes — see Ice-induced vibration and scenarios/ice_vibration_lockin/.
• A superstructure-icing module (src/tensorphysics/superstructure_icing/): analytic potential flow (cylinder / Joukowski ellipse) + Lagrangian supercooled-droplet tracking (local and total collection efficiency, ballistic and inertia-free limits), Messinger control-volume heat balance (rime/glaze, runback, evaporation, radiation) with transient 1-D growth, electro-thermal anti-icing power optimisation (skin-conduction spreading, SLSQP and SIMP 0/1 layouts), and the KG / GM / roll-period consequences of the resulting icing mass distribution — see superstructure icing report.

The coupling example is deliberately a contract test, not a validated CFD/DEM/FEM physical model. It demonstrates data flow and a conservation invariant only. The field store supports temporal linear interpolation for data types that implement arithmetic, but does not perform unit conversion or conservative mesh/particle mapping. Its history is bounded to two distinct-time samples by default; set history_limit to retain more samples for subcycling.

Checkpoint files persist orchestration metadata and JSON-compatible solver snapshots. They do not yet provide full restart/resume: each specialist solver still needs a defined restore API and compatibility checks.

Scientific workflow architecture

The scientific workflow coordinates seven cooperating concerns: agent/application interfaces; experiment control; HPC execution; specialist solvers and multiphysics; scientific data and provenance; AI model lifecycle; and scientific verification. TensorPhysics owns the domain-specific workflow and acceptance semantics, while TensorPlatform supplies shared domain-neutral runtime, governance, and lifecycle services. Agents should operate through typed, permissioned workflow tools and durable job/artifact IDs—not unrestricted shell access. Execution backends remain replaceable.

The complete platform architecture, development phases, and acceptance gates are described in docs/hpc-ai-platform-architecture.md.

Design principles

• Solver independence: TensorLBM, TensorFEM, TensorDEM, and TensorFVM remain independently usable.
• Thin orchestration: TensorPhysics coordinates solvers and data exchange; it does not reimplement numerical kernels.
• Explicit contracts: units, time advancement, field exchange, errors, and checkpoint behavior are documented.
• Testable increments: features include automated tests or a runnable example.
• Optional dependencies: the orchestration core does not require PyTorch unless a selected backend needs it.

Next milestones

1. Extend and validate RunManifest/ArtifactRef into versioned workflow and solver-capability contracts.
2. Establish local end-to-end execution with structured logs, checksums, validation reports, and durable run IDs.
3. Finish the first real solver adapters and quantitative engineering benchmarks.
4. Add an execution-backend interface (local first, HPC scheduler later) with resource limits and cancellation.
5. Build scientific artifact lineage and dataset generation before adding training/model-registry workflows.
6. Expose validated capabilities to agents with permissions, approval gates, quotas, and complete audit trails.

See docs/hpc-ai-platform-architecture.md, docs/architecture.md, docs/adapter-contracts.md, docs/roadmap.md, and docs/development.md.

Tensor ecosystem integration

This repository's role, interface boundaries, data-exchange requirements and recommended integration path are documented in Ecosystem Integration.

Optional TensorPlatform run registration

The end-to-end smoke example can register its manifest after generating the local artifact. Registration is opt-in and requires a shared-storage URI for the artifact that has already been uploaded by your storage workflow; the example does not upload artifact bytes.

Set TENSORPLATFORM_URL, TENSORPLATFORM_API_TOKEN, and TENSORPLATFORM_ORGANIZATION_ID, then run:

python examples/end_to_end_artifact_run.py \
  --output outputs/end_to_end_smoke \
  --register-platform \
  --artifact-uri s3://your-bucket/path/to/toy_history.csv

Replace the example URI with the actual shared URI of the exact file generated by the example. The SHA-256 in the manifest is computed locally; this client does not independently verify that the remote object contains identical bytes. A local file:// URI is rejected for remote registration. Without --register-platform, the example runs locally and makes no network request.

This remains a software provenance smoke test, not a validated physical simulation.

First executable research-loop demo

The first bounded TensorDEM integration slice is documented in Research Loop Demo and implemented in examples/research_loop_dem.py. It runs a real solver process, independently checks history/trajectory readability and finite values, stores outputs and validation evidence through LocalArtifactStore, emits a typed RunManifest, and recommends a next action based on the checks. Versioned goal, plan, validation-report, and research-memory contracts live in tensorphysics.research_contracts. The deterministic, fail-closed next-action policy is implemented in tensorphysics.research_policy and documented in Executable Research Methodology.

This is a software-integrity gate, not physical validation; it does not yet register the run in TensorPlatform or perform an AI-driven parameter search.

Bounded multi-run campaign

Research Campaign Demo adds a two-run, fail-closed campaign controller around the single-run demo. It varies one input parameter, independently validates each real TensorDEM run, records per-run manifest references, and stops on a failed gate. CI executes both runs. This remains a software-integrity integration exercise, not a physical sensitivity study or AI-driven research policy.

• Platform-backed campaign: TensorDEM → S3 artifacts → TensorPlatform registration, read-back, and parent-run lineage.

Persistent worker deployment

The durable task ledger is now paired with a standalone polling worker that can run independently of an interactive Agent terminal. It supports task submission and status inspection, restart recovery, bounded retries, structured event history, and a separate fail-closed validation command. Deploy and configure it using Persistent Research Worker. This is execution infrastructure: production use still requires a real authenticated Agent CLI, an independent domain validator, persistent storage, and operating system isolation. A running worker alone does not prove scientific correctness.

3-D solid element kernel (tensorphysics.solid_fem)

From-scratch small-strain isoparametric solid elements (Hex8 / Hex20) used as the structural verification backbone:

• trilinear / quadratic serendipity shape functions with analytic derivatives, 1-point / 2x2x2 / 3x3x3 Gauss rules;
• full, bbar (mean dilatation, Hex8), bbar_stab (mean dilatation plus dilatation-fluctuation stabilisation, Hex20) and sri volumetric formulations;
• Flanagan-Belytschko hourglass control for 1-point Hex8;
• J2 plasticity with radial return mapping and the analytic consistent tangent, incremental Newton-Raphson driver;
• verification benchmarks: constant-strain patch test, volumetric locking at nu = 0.4999, hourglass energy fraction, uniaxial tension vs the analytic curve, Lame thick cylinder and the elastic-perfectly-plastic limit pressure.

PYTHONPATH=src python -m pytest tests/test_solid_fem_kernel.py -q   # 47 tests
PYTHONPATH=src python scripts/p33_w2_n06_solid_fem.py               # reproducible numbers + figures

Report: docs/p33_w2_n06/REPORT.md; evidence: artifacts/p33_w2_n06/.

License

See LICENSE for the software license and LICENSE_SCOPE.md for the boundary between project software and third-party or content assets. Dataset, paper, model, customer, and other non-software assets retain their own rights and restrictions.