docs(project): expand future technical roadmap

AGENTS.md

@@ -83,6 +83,8 @@ blending them.
 
 ## Project boundary
 
+Thermophysical data workbench for generating, importing, comparing, validating and visualizing data from experiments, literature, property models and simulation backends, with leakage-aware preparation for physics-informed machine learning.
+
 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),

GUI2_PLAN.md

@@ -1,5 +1,7 @@
 # Carnopy GUI-2: active stages and release boundaries
 
+Thermophysical data workbench for generating, importing, comparing, validating and visualizing data from experiments, literature, property models and simulation backends, with leakage-aware preparation for physics-informed machine learning.
+
 This temporary document is the implementation source of truth for unfinished
 GUI-2 work. Completed implementation detail belongs in Git history and the
 short indexes under `docs/archive/`; durable implemented ownership belongs in
@@ -296,10 +298,24 @@ reconstruction, rotate, pan, zoom, camera reset, standard views, axes and
 units, scalar legends, validated linear and logarithmic presentation, points,
 wireframe, surfaces, exact picking, and deterministic teardown.
 
+Interaction should use a CAD-style scientific-navigation vocabulary: orbit,
+pan, dolly/zoom, fit-to-data, focus selected point, XY/XZ/YZ and isometric
+views, perspective and orthographic cameras, and a visible orientation control.
+The user may assign eligible fields to X, Y, Z, and scalar color, then apply
+exact filters or select levels for remaining dimensions. Scalar coloring must
+retain units, explicit ranges, missing/invalid visibility, and suitable
+sequential or diverging mapping without changing the sampled values.
+
 The QML page selects inspection-backed sources, coordinates, scalar values,
 scales, representations, and filters. Unsupported surfaces receive an explicit
 explanation rather than an approximation.
 
+Stage 7 presents sampled scalar fields on retained points or verified cells.
+It does not add arbitrary contours, isosurfaces, reconstructed slices, volume
+rendering, interpolation, smoothing, or hole filling. Those remain separate
+research directions requiring an explicit reconstruction and provenance
+contract.
+
 Authoritative image export uses a short-lived worker with explicit scene,
 camera, dimensions, scalar mapping, and rendering settings. It writes a
 guarded no-overwrite PNG and sidecar; live framebuffer capture is not

ML_PREPARATION_ROADMAP.md

@@ -2,11 +2,13 @@
 
 ## Purpose
 
-Carnopy prepares reproducible, backend-derived thermophysical datasets for
-external machine-learning and surrogate-model workflows. It is not a training
-or deployment framework. An optional diagnostic layer may fit disposable
-baseline estimators to measure prepared-dataset learnability, but it never
-persists, tunes, registers, or deploys them.
+Thermophysical data workbench for generating, importing, comparing, validating and visualizing data from experiments, literature, property models and simulation backends, with leakage-aware preparation for physics-informed machine learning.
+
+Within that product scope, Carnopy prepares reproducible, source-aware
+thermophysical datasets for external machine-learning and surrogate-model
+workflows. It is not a training or deployment framework. An optional diagnostic
+layer may fit disposable baseline estimators to measure prepared-dataset
+learnability, but it never persists, tunes, registers, or deploys them.
 
 This document separates implemented preparation behavior from possible future
 work. Future entries are design directions, not public API commitments. Each
@@ -147,6 +149,13 @@ Future interoperability should use three explicit levels:
 2. small, optional, version-qualified consumption adapters; and
 3. external training and orchestration systems that remain outside Carnopy.
 
+PyTorch is the primary planned framework-specific consumption target. The
+useful boundary includes a manifest-backed CPU tensor export, a small
+Dataset/DataLoader adapter or reference consumer, and identity-bound prediction
+result import. Physics-informed consumers must receive only genuinely available
+coordinates, fields, masks, derivatives, constraints, units, and provenance;
+Carnopy must not fabricate a physics contract to satisfy a framework API.
+
 The current and candidate technologies fall into these categories:
 
 | Technology | Roadmap classification | Rationale |

README.md

@@ -6,7 +6,7 @@
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22053741.svg)](https://doi.org/10.5281/zenodo.22053741)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-Reproducible thermophysical data pipelines integrating property models, simulation backends and validated reference data, with inspection, visualization, provenance and leakage aware preparation for physics-informed machine learning workflows.
+Thermophysical data workbench for generating, importing, comparing, validating and visualizing data from experiments, literature, property models and simulation backends, with leakage-aware preparation for physics-informed machine learning.
 
 Carnopy is an open and auditable thermophysical-data workbench. It turns an
 explicit YAML sampling specification into immutable CSV and Parquet datasets,
@@ -447,11 +447,19 @@ The planned direction develops six connected capabilities:
   provenance.
 - **Expanded visualization:** add mixture, phase-equilibrium, model-comparison,
   uncertainty, cycle, Preparation, and imported ML-result views backed only by
-  verified data contracts.
+  verified data contracts; extend exact emitted-value 3D with CAD-style
+  orbit, pan, zoom, standard and isometric views, scalar coloring, exact point
+  inspection, and selectable X/Y/Z/color projections of multidimensional data.
 - **ML interoperability:** keep Parquet canonical while evaluating PyTorch and
   selected external physics-informed and tabular-ML consumers, plus an
   identity-bound result-import contract for prediction and error analysis.
 
+Reference-dependent enthalpy, entropy, and internal-energy values remain tied
+to their recorded source, model, and reference-state context. Future comparison
+work will preserve raw values, make compatibility explicit, and allow only
+documented, reversible alignment against a declared anchor rather than silent
+normalization.
+
 The [thermophysical and simulation roadmap](THERMOPHYSICAL_ROADMAP.md) records
 the detailed source, model, backend, mixture, cycle, and visualization
 candidates. The [ML preparation roadmap](ML_PREPARATION_ROADMAP.md) records

THERMOPHYSICAL_ROADMAP.md

@@ -16,6 +16,8 @@ qualification. The current behavior remains defined by
 
 ## Product direction
 
+Thermophysical data workbench for generating, importing, comparing, validating and visualizing data from experiments, literature, property models and simulation backends, with leakage-aware preparation for physics-informed machine learning.
+
 Carnopy should not compete by reproducing every equation of state, activity
 model, process solver, or training framework. Established scientific engines
 already provide broad and specialized numerical implementations. Carnopy's
@@ -34,6 +36,27 @@ Backend count is not a success measure. A new adapter is useful only when its
 results can be identified, validated, compared, reproduced, packaged, and
 explained at least as rigorously as current CoolProp runs.
 
+## Source and provider roles
+
+Future integrations must preserve what kind of scientific source produced a
+value instead of calling every provider a backend:
+
+- **experimental and literature evidence** supplies reported observations,
+  methods, uncertainty, citations, samples, and source-record identity;
+- **property engines** evaluate thermophysical or equilibrium properties from
+  declared states, compositions, models, and parameters;
+- **simulation engines** solve process, cycle, reacting-system, or field
+  models and return typed state, topology, balance, convergence, and solver
+  evidence; and
+- **external surrogate results** supply predictions or uncertainties bound to
+  an exact Carnopy Preparation bundle and external run identity.
+
+ThermoML is the first structured evidence target. CoolProp, ThermoPack, teqp,
+and `thermo` are candidate property-engine paths with different scientific
+coverage. TESPy, DWSIM, Cantera, and IDAES are candidate simulation paths whose
+cycle, flowsheet, reaction, optimization, and property-package responsibilities
+must remain explicit rather than being flattened into one generic adapter.
+
 ## Recommended sequence
 
 1. Establish a validated source/import contract, beginning with ThermoML.
@@ -94,6 +117,12 @@ The importer must not treat every record as equally suitable for validation.
 Method, uncertainty, phase, composition, and domain compatibility must remain
 visible so users can decide what constitutes relevant evidence.
 
+The first compatibility target should cover archive ThermoML XML and its
+corresponding JSON representation through one normalized evidence model. Exact
+source bytes remain immutable. Unsupported record families or fields must be
+reported and retained as explicit import limitations rather than discarded or
+guessed into a simpler schema.
+
 ### Comparison and validation products
 
 Model-to-reference comparison should align only scientifically compatible
@@ -115,6 +144,27 @@ software versions, covariance or uncertainty information when available, and
 an immutable result identity. Fitted parameters must never silently replace a
 backend default.
 
+## Reference-state alignment for enthalpy, entropy, and internal energy
+
+Specific enthalpy, entropy, and internal energy require an explicit reference
+context. Future imported and multi-engine comparisons must retain:
+
+- the raw reported or generated value and unit;
+- source, backend, model, version, composition, and phase identity;
+- the declared reference-state convention when one is supplied;
+- any reference temperature, pressure, phase, composition, and anchor values;
+- whether the reference information is source-reported, backend-defined,
+  user-declared, derived through a reviewed transformation, or unavailable;
+- the exact offset or transformation used for an aligned comparison; and
+- both the original and aligned value identities.
+
+Absolute values may be compared directly only when their reference contexts
+are compatible. Otherwise Carnopy should prefer reference-independent
+differences where scientifically valid, report the incompatibility, or allow an
+explicit reversible rebasing against a sufficiently defined common anchor.
+Rebasing must never alter source artifacts, hide the original values, or occur
+as an automatic plotting or import convenience.
+
 ## Mixtures and phase equilibria
 
 ### Composition contract
@@ -239,6 +289,10 @@ through a new typed result contract.
   networks rather than ordinary nonreacting property tables.
 - **IDAES** is a later candidate for full process flowsheets and optimization
   when a use case needs that broader process-modeling scope.
+- **DWSIM** is a later candidate for process-flowsheet execution or typed result
+  import through its automation surfaces. A reviewed adapter must preserve the
+  flowsheet, property-package, unit-operation, solver, stream, and convergence
+  identities rather than exposing mutable simulator objects as Carnopy state.
 
 Each adapter must remain optional and worker-owned. Carnopy configuration and
 results should not expose mutable engine objects as public scientific state.
@@ -262,6 +316,38 @@ artifacts. Candidate views include:
 - imported ML prediction parity, residual, error-domain, learning-curve, and
   uncertainty-calibration views.
 
+### Interactive 3D and multidimensional projections
+
+The native 3D direction extends exact emitted-value scenes into a scientific
+data-navigation workbench:
+
+- CAD-style orbit, pan, dolly/zoom, fit-to-data, camera reset, and focus on an
+  exact selected point;
+- standard XY, XZ, and YZ views plus isometric views, with perspective and
+  orthographic camera choices and a visible orientation control;
+- points, verified wireframes, verified surfaces, and scalar-colored
+  representations with explicit units and linear or logarithmic mapping;
+- sequential and diverging scalar palettes selected according to declared
+  value semantics, with explicit user-controlled ranges and visible missing or
+  invalid values;
+- exact point picking linked to the complete source row, source identity,
+  diagnostics, and provenance;
+- assignment of eligible fields to X, Y, Z, and scalar color without
+  regenerating or rewriting the source artifact;
+- exact categorical and numeric filtering, faceting, and coordinate-level
+  stepping for dimensions not assigned to visible axes;
+- linked 2D sections or tables that preserve the selected 3D point and source
+  context; and
+- deterministic image export recording scene, camera, dimensions,
+  representation, filters, scalar mapping, and source identities.
+
+These are projections of sampled multidimensional data. A scalar attached to
+emitted points or verified cells is a sampled scalar field; it is not silently
+promoted to a continuous field. Arbitrary contours, reconstructed slices,
+isosurfaces, volume rendering, smoothing, or hole filling require a separate
+scientific contract that states the reconstruction or interpolation method,
+domain, uncertainty, and provenance.
+
 Visualization must preserve missing data, phase boundaries, uncertainty,
 source identity, and failures. Interpolation, smoothing, derived envelopes, or
 topological paths require an explicit scientific contract and must never be
@@ -297,3 +383,5 @@ metrics, and result visualization are detailed in
 - OpenMDAO, [pyCycle](https://github.com/openmdao/pycycle).
 - Cantera, [reactor networks](https://cantera.org/stable/reference/reactors/index.html).
 - IDAES, [process systems engineering framework](https://idaes.org/software/).
+- DWSIM, [automation documentation](https://dwsim.org/wiki/index.php?title=Automation)
+  and [tutorials](https://dwsim.org/tutorials/en/index.html).

docs/agent-guides/SCIENTIFIC_CONTRACTS.md

@@ -14,8 +14,13 @@ scientific and public contracts or make an unimplemented direction available.
 
 ## Purpose and scope
 
-Carnopy generates reproducible, backend-derived synthetic thermophysical
-datasets for machine-learning, surrogate-model, and engineering workflows.
+Thermophysical data workbench for generating, importing, comparing, validating and visualizing data from experiments, literature, property models and simulation backends, with leakage-aware preparation for physics-informed machine learning.
+
+The current implemented contract is the first bounded part of that product
+scope: Carnopy generates reproducible, backend-derived synthetic
+thermophysical datasets for machine-learning, surrogate-model, and engineering
+workflows. Import, additional sources, and the other future capabilities remain
+roadmap directions until separately implemented and accepted.
 
 Carnopy is not: