Release/0.1.0a5

.github/CONTRIBUTING.md

@@ -83,11 +83,12 @@ Run the current source-checkout desktop application with:
 uv run --locked carnopy-gui
 ```
 
-Version `0.1.0a3` contains the historical Linux-first Widgets GUI. The current
-`0.1.0a4` source has completed tested QML parity, both public desktop
-commands launch the same QML application, and the duplicate Widgets
-presentation is removed. `carnopy-gui` is the canonical command;
-`carnopy-app` remains a compatibility alias for `0.1.0a4`.
+Version `0.1.0a3` contains the historical Linux-first Widgets GUI, and
+`0.1.0a4` completed the migration to one tested QML application. Current
+`0.1.0a5` source adds the structured Model Sweep and ML Preparation workflows,
+the custom frame, and direct post-generation plotting. `carnopy-gui` is the
+canonical command; `carnopy-app` remains the compatibility alias introduced
+for `0.1.0a4`.
 
 Worker-backed inspection and preview changes must use stable table IDs rather
 than GUI-supplied artifact paths. Cover traversal, symlink, integrity-token,

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -14,7 +14,7 @@ body:
     attributes:
       label: Carnopy and Python versions
       description: Include `carnopy --version` or `carnopy-app --version`, plus `python --version`.
-      placeholder: "carnopy 0.1.0a3 or carnopy-app 0.1.0a3; Python 3.12.12"
+      placeholder: "carnopy 0.1.0a5 or carnopy-gui 0.1.0a5; Python 3.12.12"
     validations:
       required: true
   - type: dropdown

.github/ISSUE_TEMPLATE/scientific-discrepancy.yml

@@ -14,7 +14,7 @@ body:
     id: versions
     attributes:
       label: Carnopy and CoolProp versions
-      placeholder: "Carnopy 0.1.0a3; CoolProp 8.0.0"
+      placeholder: "Carnopy 0.1.0a5; CoolProp 8.0.0"
     validations:
       required: true
   - type: input

AGENTS.md

@@ -68,9 +68,9 @@ reading.
 | Work being performed | Required guidance |
 | --- | --- |
 | Any implementation, test, documentation, or commit handoff | [Development and contribution workflow](docs/agent-guides/DEVELOPMENT.md) |
-| Product identity, boundaries, future scope, or roadmap priority | Maintainer-local `PRODUCT_SCOPE.md` and `.agents/private/PRODUCT_STRATEGY.md` when present, plus the public [README Future Scope](README.md#future-scope) |
+| Product identity, boundaries, future scope, or roadmap priority | Maintainer-local `PRODUCT_SCOPE.md` and `.agents/private/PRODUCT_STRATEGY.md` when present, plus the public [README Future Scope](README.md#future-scope), [thermophysical roadmap](THERMOPHYSICAL_ROADMAP.md), and [ML preparation roadmap](ML_PREPARATION_ROADMAP.md) |
 | Delegating work or changing project-agent definitions | [Codex delegation policy](docs/agent-guides/DELEGATION.md) and the applicable files under `.codex/agents/` |
-| Scientific behavior, configuration, sampling, CLI/API, rows, provenance, preparation, visualization, or core architecture | [Public scientific and application contracts](docs/agent-guides/SCIENTIFIC_CONTRACTS.md) |
+| Scientific behavior, configuration, sampling, CLI/API, rows, provenance, preparation, visualization, or core architecture | [Public scientific and application contracts](docs/agent-guides/SCIENTIFIC_CONTRACTS.md), plus the [thermophysical roadmap](THERMOPHYSICAL_ROADMAP.md) when planning future sources, mixtures, models, backends, cycles, or scientific visualization |
 | Desktop controllers, QML, Widgets, worker boundaries, packaging of desktop resources, native 3D, or frontend retirement | [Desktop architecture](DESKTOP_ARCHITECTURE.md) and, while GUI-2 is active, [GUI-2 plan](GUI2_PLAN.md) |
 | Preparation workflows, diagnostics, feature engineering, or research directions | [Public scientific and application contracts](docs/agent-guides/SCIENTIFIC_CONTRACTS.md) and [ML preparation roadmap](ML_PREPARATION_ROADMAP.md) |
 | Packaging metadata, dependency extras, distribution contents, CI publishing, tags, or releases | [Packaging and release safeguards](docs/agent-guides/RELEASE.md) and [Development and contribution workflow](docs/agent-guides/DEVELOPMENT.md) |
@@ -85,10 +85,12 @@ blending them.
 
 Carnopy is an open and auditable thermophysical-data workbench. Current
 behavior and exclusions live in the tracked scientific contracts. The public
-direction is summarized in the [README Future Scope](README.md#future-scope);
-maintainer-local product files may order future work when present. Planned
-directions are not implemented capabilities or authority to broaden a public
-contract without maintainer approval.
+direction is summarized in the [README Future Scope](README.md#future-scope),
+[thermophysical roadmap](THERMOPHYSICAL_ROADMAP.md), and
+[ML preparation roadmap](ML_PREPARATION_ROADMAP.md); maintainer-local product
+files may order future work when present. Planned directions are not
+implemented capabilities or authority to broaden a public contract without
+maintainer approval.
 
 ## Always-on safeguards
 

CITATION.cff

@@ -2,9 +2,7 @@ cff-version: 1.2.0
 message: "To cite Carnopy, use the metadata below."
 title: "Carnopy"
 type: software
-version: "0.1.0a4"
-doi: "10.5281/zenodo.21709965"
-date-released: "2026-07-30"
+version: "0.1.0a5"
 license: MIT
 
 authors:

DESKTOP_ARCHITECTURE.md

@@ -69,14 +69,13 @@ The source tree has one desktop presentation implementation:
 - the QML Activity page, guarded end-to-end cross-page/close parity, public
   launcher migration, and Widgets retirement are implemented.
 
-The release version is `0.1.0a4`. Both public launchers select the
-tested QML parity application; Carnopy does not ship two normal desktop
-applications or a frontend selector. The resulting QML application is the
-planned `0.1.0a4` alpha checkpoint. Later sweep, preparation, and native-3D
-stages are not prerequisites for that release. Stage 3 implementation, remote
-CI, the complete local gate, and native acceptance passed on 2026-07-30. Its
-accepted screenshot and historical implementation index are tracked under
-`docs/`, and this document records the accepted Stage 3 architecture.
+The release-candidate version is `0.1.0a5`. Both public launchers select the
+same QML application; Carnopy does not ship two normal desktop applications or
+a frontend selector. This release includes the accepted structured Model Sweep
+and ML Preparation workflows, the custom desktop frame, and direct
+post-generation session-plot handoff. Native-3D Stages 6–8 remain outside its
+scope. The historical `0.1.0a4` Stage 3 checkpoint and later Stage 4/5
+acceptance records remain indexed under `docs/`.
 
 ## Authority map
 
@@ -90,6 +89,7 @@ Use the narrowest applicable authority:
 | `GUI2_PLAN.md` | Temporary GUI-2 scope, sequencing, decisions, and acceptance status |
 | `DESKTOP_ARCHITECTURE.md` | Durable implemented desktop structure and evolution |
 | `README.md` | Public product summary plus user-facing installation and workflow guidance |
+| `THERMOPHYSICAL_ROADMAP.md` and `ML_PREPARATION_ROADMAP.md` | Public future scientific and interoperability candidates; not implementation authority |
 
 When these disagree, do not silently blend them. Repository source and tests
 establish current behavior, while `AGENTS.md`, its task-routed authoritative
@@ -520,6 +520,16 @@ samples per fluid facet so their outlines cannot obscure the color mesh;
 invalid emitted states retain explicit cross markers and remain counted in the
 sidecar.
 
+Future source, mixture, property-backend, and cycle adapters described in
+`THERMOPHYSICAL_ROADMAP.md` remain worker-owned scientific integrations. QML may
+present typed capability, result, and failure projections but must not call
+those engines or infer their support. In particular, a cycle path requires a
+new typed result containing ordered topology and process states; the current
+emitted-state p-v and T-s series cannot be promoted into cycle paths by
+presentation logic. A future imported ML-result workflow follows the same
+boundary: Python validates exact Preparation, partition, row, target, unit, and
+artifact identities before QML can visualize predictions or errors.
+
 ### `WorkerClient`
 
 `WorkerClient` is transport, not workflow logic. It starts one `QProcess`,

GUI2_PLAN.md

@@ -12,16 +12,18 @@ finished application.
 
 ## Release and frontend baseline
 
-- `0.1.0a4` is the published baseline and contains the accepted Stage 3 QML
-  parity application.
+- `0.1.0a5` is the current release candidate. It contains the accepted Stage 5
+  structured Model Sweep and ML Preparation workflows, the custom desktop
+  frame, and direct post-generation session plotting.
+- `0.1.0a4` is the historical Stage 3 QML-parity release.
 - `0.1.0a3` is the historical GUI-1 release and contains the retired Widgets
   presentation.
 - `carnopy-gui` is canonical. `carnopy-app` launches the same QML application
-  as a compatibility alias for `0.1.0a4`.
+  as the compatibility alias introduced for `0.1.0a4`.
 - The obsolete Widgets presentation is deleted. Carnopy does not ship a
   frontend selector or two normal desktop applications.
-- `0.1.0a4` is a bounded post-Stage-3 release. It does not wait for sweep and
-  preparation QML workflows or native 3D.
+- `0.1.0a5` remains bounded before native 3D; Stages 6–8 are not part of this
+  release.
 - The `app` extra is the cross-platform QML application. A future optional
   `3d` extra may add the native VTK bridge to that application; it is not a
   second GUI.

ML_PREPARATION_ROADMAP.md

@@ -109,7 +109,7 @@ discoverability remain a post-Stage-5 UX follow-up rather than preparation
 science or an unfinished data contract. The accepted implementation record is
 indexed in [`docs/archive/GUI2_STAGE5.md`](docs/archive/GUI2_STAGE5.md).
 
-## Reviewed future direction — Optional PyTorch dataset export
+## Reviewed future direction: Optional PyTorch dataset export
 
 The product sequence now prioritizes desktop workflow depth and then source
 breadth. This bounded PyTorch consumption format remains reviewed but planned
@@ -137,6 +137,87 @@ supported Python and platform matrix before changing packaging or public
 templates. It must not narrow the supported base-install matrix merely to add
 this derived format.
 
+## Framework interoperability boundary
+
+Carnopy should make prepared thermophysical data easy to consume without
+becoming a training framework or accumulating unrelated runtime dependencies.
+Future interoperability should use three explicit levels:
+
+1. framework-neutral files and manifests owned by Carnopy;
+2. small, optional, version-qualified consumption adapters; and
+3. external training and orchestration systems that remain outside Carnopy.
+
+The current and candidate technologies fall into these categories:
+
+| Technology | Roadmap classification | Rationale |
+| --- | --- | --- |
+| SafeTensors | Implemented derived export | Framework-neutral tensor storage with deterministic manifest evidence; Parquet remains canonical. |
+| PyTorch | Reviewed optional adapter candidate | A plain `.pt` tensor dictionary, or a documented Dataset/DataLoader consumer adapter, may reduce integration effort without moving training into Carnopy. |
+| DeepXDE | External physics-informed consumer | A candidate example integration for PINNs and scientific ML over prepared bundles, not a Carnopy dependency or execution engine. |
+| NVIDIA PhysicsNeMo | External physics-informed consumer | A candidate consumer for PINNs and neural operators when exact coordinates, fields, constraints, and provenance can be mapped explicitly. |
+| XGBoost | Optional external tabular benchmark | Useful for nonlinear regression baselines or downstream studies only when a concrete comparison need justifies an adapter. |
+| LightGBM | Optional external tabular benchmark | Potentially useful for large prepared tables, but not added merely to increase estimator count. |
+| CatBoost | Optional external tabular benchmark | Potentially useful when categorical fluid or model identities remain native categorical features; the current one-hot representation is not a drop-in CatBoost contract. |
+| DeepSpeed | External distributed-training infrastructure | Training optimization, checkpointing, and distributed execution remain consumer responsibilities. |
+| Ray | External orchestration and tuning infrastructure | A future adapter requires a concrete distributed or hyperparameter-search workflow; Ray is not part of preparation itself. |
+| Helion | Out of scope for Carnopy core | A GPU kernel language sits below Carnopy's data and provenance abstraction. |
+| vLLM | Out of scope for thermophysical ML Preparation | LLM inference and serving do not address Carnopy's tabular scientific-data contract. |
+
+These classifications prevent name-driven dependency growth. An adapter must
+solve a demonstrated workflow, preserve the exact Preparation bundle identity,
+and pass dependency, platform, serialization, security, and maintenance review.
+
+Flatten operations are tensor reshaping or neural-network layer choices, not
+thermophysical feature transformations. Cross-entropy is a classification loss
+and is relevant only to an explicit future classification target such as phase
+or validity class. It is not an appropriate default for continuous property
+regression. More relevant external regression measures include mean absolute
+error, root mean squared error, Huber loss, carefully defined relative error,
+maximum error, and physics-consistency residuals. Carnopy may define how
+imported evaluation evidence is interpreted, but it does not own the training
+loop or loss optimization.
+
+## Imported prediction results and ML visualization
+
+A useful ML workflow requires more than writing arrays. A future reviewed
+result-import contract should let Carnopy inspect and compare outputs from an
+external trainer without loading executable model objects. Every imported
+result must bind to:
+
+- the exact Preparation bundle and manifest identity;
+- scenario and partition identities;
+- source dataset or sweep identity;
+- feature, target, unit, row, and transformation definitions;
+- external framework, model, training-run, and artifact identities;
+- prediction and uncertainty column semantics;
+- declared metrics and aggregation domains; and
+- immutable imported bytes with hashes and provenance.
+
+Imported results must reject or clearly quarantine incompatible row identities,
+partitions, targets, units, inverse transformations, and stale source bindings.
+Carnopy should not deserialize arbitrary checkpoints, execute user models, or
+infer missing training metadata.
+
+Candidate result views include:
+
+- predicted-versus-reference parity plots;
+- residual distributions and quantile summaries;
+- error by fluid, phase, backend model, temperature, pressure, composition, and
+  validity domain;
+- train, validation, test, and holdout comparisons;
+- learning and validation curves when supplied by the external trainer;
+- uncertainty calibration and coverage plots; and
+- side-by-side model comparisons over the exact same accepted rows.
+
+The result-import and visualization contract should work across PyTorch,
+DeepXDE, PhysicsNeMo, scikit-learn, XGBoost, LightGBM, CatBoost, and other
+external consumers without making any one framework the scientific authority.
+
+Framework-ready future exports should preserve coordinates, properties, units,
+composition, domain masks, phase labels, available derivatives, physical
+constraints, and complete provenance. They must not fabricate derivative or
+constraint fields merely because a consumer framework can accept them.
+
 ## Durable preparation rules
 
 - Split assignment precedes every fitted transformation.
@@ -309,6 +390,25 @@ not part of the preparation roadmap.
 - scikit-learn, [Preprocessing
   reference](https://scikit-learn.org/stable/api/sklearn.preprocessing.html),
   for the semantics and tradeoffs of common transformations.
+- scikit-learn, [Model evaluation](https://scikit-learn.org/stable/modules/model_evaluation.html)
+  and [learning curves](https://scikit-learn.org/stable/modules/learning_curve.html).
+- PyTorch, [`torch.flatten`](https://docs.pytorch.org/docs/stable/generated/torch.flatten.html)
+  and [`CrossEntropyLoss`](https://docs.pytorch.org/docs/stable/generated/torch.nn.CrossEntropyLoss.html),
+  for their actual tensor and classification semantics.
+- [DeepXDE](https://github.com/lululxvi/deepxde) and
+  [NVIDIA PhysicsNeMo](https://docs.nvidia.com/deeplearning/physicsnemo/physicsnemo-core/),
+  as candidate external physics-informed consumers.
+- [XGBoost](https://xgboost.readthedocs.io/en/stable/index.html),
+  [LightGBM](https://lightgbm.readthedocs.io/en/stable/), and
+  [CatBoost](https://catboost.ai/docs/en/), as candidate external tabular
+  consumers.
+- [DeepSpeed](https://deepspeed.readthedocs.io/en/stable/index.html),
+  [Ray Tune](https://docs.ray.io/en/latest/tune/tutorials/tune-lifecycle.html),
+  [Helion](https://pytorch.org/blog/helion/), and
+  [vLLM](https://docs.vllm.ai/en/stable/index.html), for the boundaries between
+  data preparation, external orchestration, kernel generation, and LLM serving.
+- Hugging Face, [SafeTensors](https://huggingface.co/docs/safetensors/index), for
+  the implemented framework-neutral tensor format.
 - Brunton, Proctor, and Kutz, [Discovering governing equations from data by
   sparse identification of nonlinear dynamical
   systems](https://doi.org/10.1073/pnas.1517384113), *PNAS* 113 (2016),