v0.22.0 — Physical diagnostics and mechanism evidence

v0.22.0 physical diagnostics and mechanism evidence

This increment connects original-field regions, signed transfers, matched spatial changes
and defined control-volume budgets to the existing research workspace. The host can use
those observations to test a physical explanation instead of assembling separate scalar
spreadsheets, plots and prose by hand. Scientific interpretation remains with the host and author.

Implemented

• field_integral distinguishes density times physical measure, already integrated element
  totals, vector flux dotted with oriented area, weighted means and separately supplied
  positive/negative integrated powers. Temperature-area sums are not heat. Missing values
  remain unavailable rather than becoming zero.
• Regions use explicit overlap fractions, declared centroid assignment or original planar
  polygon clipping. The geometric partition check detects actual overlaps and uncovered
  portions, not merely fractions adding to one. Curved walls require native reports or
  suitable externally defined fractions. Shapely is an optional geometry dependency.
• field_difference matches physical coordinates, measures and original polygons when
  supplied, retaining both original means and the difference. Equal row counts are not a
  spatial mapping. Absolute-temperature differences use K; percentages of absolute-temperature
  integrals are refused because they depend on temperature origin.
• energy_budget retains input, output, source, storage and the resulting residual with
  a stated control volume. A steady-state storage omission must be explicit. A remainder
  does not become an independently observed path or a model-validation result.
• An optional PyFluent reference backend reads saved CASE/DATA, original boundary polygons,
  temperature, heat flux and native whole-surface or coordinate-clipped reports without
  solving or writing back. The actual backend trial used Windows, Fluent 2023 R1 and
  PyFluent 0.20. Neutral NPZ/CSV consumption does not require Fluent or a license.
• research --diagnostics attaches those calculations, complementary figures and source-bound
  evidence to a new copy of an existing workspace. Compact current scalar readings in
  research-context.json point to complete result definitions and source locations.
  Generated figure sources, editable SVG/PDF, PNG/TIFF and author-local scripts travel together.
• Computed comparisons consume explicit physical supports: shared steady/fixed/window states,
  event-relative observations or consistently defined event timings. Native events and saved
  threshold markers are not interchangeable; only named conditions claimed fixed are matched.
• Literature excerpts can be checked at exact source lines or pages of page-delimited extracted
  text. PDF page index and a printed-page label remain distinct. This checks location, not
  whether the source's scientific claim transfers to a new problem.
• Source-value and definition changes refresh related diagnostics, figures and bound values
  while retaining author scripts and prose. In-place editing of a returned workspace and
  changed diagnostic source paths are recognized. Affected interpretation still needs the host.
• Five existing bundled skills now explain these actual tools and their scientific use.
  Adjacent native Word table captions have explicit spacing without changing body typography.

Install and try

Use CPython 3.10–3.12 and the matching source checkout/archive:

python -m pip install ".[docs,geometry]"
python examples/physical-diagnostics/run_example.py output/physical-demo

Open output/physical-demo/candidate/manuscript.docx. The
tutorial provides six constructed unequal-area
faces, opposing transfers, a matched difference and a separate budget. It replays disclosed
recorded host prose through Methods, Results, Discussion and Conclusions, five figures and
two native tables. The original arrays are not CFD results; the separate budget does not
validate them. --prepare-only leaves the drafts for a host to write.

Examples are in the source archive, not the wheel. For a release wheel:

python -m pip install "./cfd_paper_agent-0.22.0-py3-none-any.whl[docs,geometry]"

Use the optional fluent extra only in an environment that can access the licensed solver.
The research guide covers saved-results extraction, diagnostic
declarations, manuscript attachment and continued author editing. The core works without a
model API; the host supplies the research judgment and prose.

Actual research use and what improved

A known four-case conjugate-cooling task used existing original surface fields, regional
native reports and signed reconstructed conduction. It distinguished a moving hot footprint
from fixed-coordinate changes, mean-temperature composition from heat accounting, and local
wetted area from per-area heat transfer. The figures and manuscript retained the differing
structure–location responses rather than forcing a universal enhancement explanation.

Two isolated first writers received the same new-evidence materials. Both produced supported
scientific interpretations. The preceding tool route required task-specific regional mathematics
and a scalar bridge; the candidate used reusable physical calculations and bound figure/text
outputs. This supports less bespoke processing, not superior autonomous discovery or a measured
percentage saving in time/tokens. Initial candidates and their differing strengths were retained.
Two local wording corrections were kept separate from product improvements.

The first-use trial exposed stale attached-result context; the entry now publishes current
diagnostic readings before writing. Independent numerical review also found an origin-dependent
temperature-integral comparison and a false polygon-partition acceptance. Both have reproductions
and targeted fixes; valid real-region numerical values were unchanged.

Existing thermal-model histories separately demonstrated valid common-time comparisons and
rejection of own-event observations consumed as equal-time evidence. This was a time-support
regression, not a multiphase CFD validation. Separate source/region-definition perturbations
exercised targeted update and retention of author prose and local plotting scripts. Those copies
are software exercises, not additional scientific cases.

Actual Word/PDF pages and figures were inspected locally. Generic platform CI and installed-wheel
examples exercise the software; they do not establish cross-platform native solver behavior or
independent physical validation. Release checks are recorded in the matching GitHub workflow runs.

Scope and next work

The native reference path is limited to the tested surface quantities and backend environment.
STAR-CCM+ recognition/export guidance and the existing limited neutral VTK path are unchanged.
Planar clipping does not become a generic mesh engine. Gradient reconstruction and a budget
remainder from the same saved solution remain complementary diagnostics, not independent validation.

The Workbench plan retains limited Word-edit return
and document profiles for v0.23, and second-host/heterogeneous evaluation for v0.24. No automatic
SCI readiness, universal solver coverage or new simulation capability is claimed. The
v0.21.0 notes remain the previous release record.

Validated by Windows/Linux Python 3.10–3.12 and installed-package CI: all seven jobs passed. The merged source tree is identical to the verified candidate. Attached wheel and source archive are the CI-built distributions; the example ZIP contains only redistributable constructed data.