diff --git a/AGENTS.md b/AGENTS.md index 61a1bba..f0c0789 100644 --- a/AGENTS.md +++ b/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), diff --git a/GUI2_PLAN.md b/GUI2_PLAN.md index a071720..ec13ee9 100644 --- a/GUI2_PLAN.md +++ b/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 diff --git a/ML_PREPARATION_ROADMAP.md b/ML_PREPARATION_ROADMAP.md index b123a14..342964d 100644 --- a/ML_PREPARATION_ROADMAP.md +++ b/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 | diff --git a/README.md b/README.md index 707e94a..fcbe9bd 100644 --- a/README.md +++ b/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 diff --git a/THERMOPHYSICAL_ROADMAP.md b/THERMOPHYSICAL_ROADMAP.md index ba7225d..b9aaec1 100644 --- a/THERMOPHYSICAL_ROADMAP.md +++ b/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). diff --git a/docs/agent-guides/SCIENTIFIC_CONTRACTS.md b/docs/agent-guides/SCIENTIFIC_CONTRACTS.md index 603134d..cfa6dab 100644 --- a/docs/agent-guides/SCIENTIFIC_CONTRACTS.md +++ b/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: