# PolyCFD roadmap

**Direction agreed with the project owner; current implementation reviewed 2026-09-19; AMReX alignment planning added 2026-09-26.**
This document defines future work and its acceptance conditions. The [physics guide](https://github.com/hankbeasley/polycfd/blob/main/docs/PHYSICS_GUIDE.md)
and [runtime contracts](https://github.com/hankbeasley/polycfd/blob/main/docs/RUNTIME_CONTRACTS.md) describe what works today. Current milestone and
task status is maintained on the [work board](/docs/WORKBOARD); no roadmap workflow is delivered
merely because its design or an existing building block is available.

## Product direction

Build an accessible CFD system for engineers evaluating fan enclosures and students exploring
fluid behavior. Begin with complete local workflows for airflow and pressure drop. Extend those
workflows to heat transfer and then buoyancy, including room cooling with AC/fans and air-side
studies of outdoor condensers. Keep the architecture extensible to additional physics.

The numerical direction is Cartesian, matrix-free, multiblock and multiresolution, drawing on
the capabilities of [AMReX](https://amrex-codes.github.io/amrex/docs_html/Introduction.html).
Its adaptive-grid, embedded-boundary and parallel-computing capabilities are a reference for
scope, not a commitment to reproduce every feature or adopt its implementation.

The product should support a common scenario through a clear C# API, CLI, browser and eventually
coding agents. A model created by a person or an agent should enter the same geometry preparation,
validation, execution and result workflow. [SimScale's workbench](https://www.simscale.com/docs/simulation-setup/)
is a reference for the connected geometry/setup/run/results experience.

### Priorities and constraints

- Complete useful local workflows before cloud orchestration.
- Deliver airflow and pressure drop first, heat transfer second, buoyancy third.
- Start with one GPU per simulation. Scale up through better memory use, numerical efficiency,
  larger GPUs and selective spatial resolution. Neither a worker fleet nor distributed solves
  is an initial scalability requirement.
- Retain C#/.NET, ILGPU, ASP.NET and React/Three.js unless measured requirements justify a change.
  Preserve native local execution and the supported ILGPU CPU fallback.
- Support complex stationary and moving geometry, with physical accuracy established for each
  supported use. Preserve the existing rotating-body capability while extending its validation.
- Make data structures, errors, examples and operations usable by both people and agents from
  the beginning. Choose agent providers and deeper autonomy later.
- During pre-release development, backward compatibility is not a requirement. Remove superseded
  code as features change and update maintained callers, data, tests and documentation together.
  Preserve scientific capabilities and reference checks without retaining obsolete interfaces.
- Keep this document focused on current priorities and future work. When work ships, put its
  supported behavior and limits in the current guides and update this roadmap; do not accumulate
  historical checklists or repeat experiment logs here.

## Starting point

| Area | Available now | Gap relevant to this roadmap |
| --- | --- | --- |
| Flow solver | Constant-density incompressible MAC solver; matrix-free pressure; Jacobi/MG; CUDA and CPU accelerator | One simulation block; no local mesh refinement or distributed solve |
| Geometry | SDF/STL cut cells, static wall shear, geometry-aware advection, rigid rotation and component-aware moving pressure | General assembly authoring, moving viscous-wall coefficients and general moving-body force validation |
| Public runtime | Typed C#/JSON scenario 1.2 with preflight/resolver and named measurements; independent session API and selective captures | Extend beyond one solid and bounded initial/source/motion profiles |
| Reproducibility | Shared scenario records plus versioned scientific verification; asset snapshots/hashes, resolved settings and replay | Conversion across future format/resolver revisions and numerical checkpoint/restart |
| CLI | General validate/run/status/replay, metadata inspection, parameter studies and measured comparisons, uncalibrated resource preflight and numerical validation commands | Hardware-calibrated resource budgets |
| Browser | Local/live viewing, slices, probes, geometry and bounded frame capture | Create/edit/validate/submit scenarios and manage runs |
| Measurements | Reusable named aligned-section flow/static pressure, pressure differences, domain mass balance and windows in API/CLI; independent plane-channel flow/pressure accuracy and refinement; case forces, reference metrics and timing | Enclosure/fan validation and accuracy evidence for practical layouts |
| Thermal physics | No temperature equation, solid thermal model or buoyancy coupling | Temperature fields, materials, thermal BCs, heat balances and coupled validation |
| Deployment | Native local runtime and ASP.NET viewer host | Worker image, job protocol, remote execution and orchestration |

Evidence for this boundary is in the [runtime guide](https://github.com/hankbeasley/polycfd/blob/main/docs/RUNTIME_CONTRACTS.md),
[physics guide](https://github.com/hankbeasley/polycfd/blob/main/docs/PHYSICS_GUIDE.md), [section guide](https://github.com/hankbeasley/polycfd/blob/main/docs/SECTION_MEASUREMENTS.md),
[validation CLI](https://github.com/hankbeasley/polycfd/blob/main/validation/PolyCfd.Validation/README.md),
[simulation definition](https://github.com/hankbeasley/polycfd/blob/main/src/PolyCfd.Gpu/Integration/SimulationDefinition.cs),
[grid block](https://github.com/hankbeasley/polycfd/blob/main/src/PolyCfd.Core/Core/GridBlock.cs) and
[web host](https://github.com/hankbeasley/polycfd/blob/main/src/PolyCfd.Web/README.md).
Pressure multigrid's coarse solve levels are not locally refined simulation grids.
The moving-fan regression establishes numerical stability within its test scope; it does not
establish a general fan performance curve or validated enclosure cooling prediction.

## User outcomes and release order

| Release outcome | What a user can do | Required milestones |
| --- | --- | --- |
| Local airflow workbench | Create a supported enclosure, define airflow, measure flow and pressure drop, change a parameter, compare and reproduce results from CLI or browser | W1–W4 |
| Forced cooling workflow | Add temperature, heat loads and thermal boundary conditions; inspect mixing, temperature response and heat balance | T1–T2, W4 |
| Buoyant room workflow | Combine fan/AC supply, heat loads and temperature-driven air movement; compare layouts within a validated regime | T3, T1–T2 |
| Larger and more detailed local cases | Use one GPU efficiently, multiple blocks and selected finer regions; improve moving-body fidelity where needed | S1–S3 and G1 as required by the case |
| Portable execution | Execute the same supported scenario natively or in a GPU worker, then on a remote machine | C1–C2 after the local workflow |
| Agent-assisted simulation | Describe a supported scenario, connect modeling tools, run and revise experiments, and obtain a traceable result | Agent-ready W1–W4 foundation, then A1–A2 |

W1–W4 are the initial product sequence. Next, prioritize T1, an initial T2 cooling workflow,
and T3 in that order. General conjugate heat transfer need not delay the first buoyant room case.
S1 profiling supports every release. Bring forward S2/S3 or G1 only when resolution, capacity
or moving-wall accuracy blocks an agreed case; full AMR is not a prerequisite for the first
local workbench or simple thermal examples. Start each numerical capability on the smallest
validated problem, then extend the complete workflow to use it.

## First: complete local airflow workflows

### W1 — Portable scenario and public API

**Outcome:** a person or program defines a supported flow problem without adding a validation case.

1. Define a versioned scenario schema: units, domain, named geometry assets/parts, fluid properties,
   boundary regions, initial conditions, sources/motion, mesh settings, measurements and outputs.
   Separate scientific settings from local paths, device selection and execution destinations.
2. Add scenario validation and resolution into the existing runtime: supported capabilities,
   missing/conflicting inputs, explicit defaults and stable diagnostic codes with field paths.
   Initially accept the existing six-face pressure/partial-velocity contract; reject unsupported
   interior or independent pressure regions rather than implying they already work.
3. Provide a small typed C# authoring API and data-based equivalents for common initial conditions,
   geometry and BCs. Keep advanced code factories available through explicit extension points;
   do not attempt to serialize arbitrary delegates.
4. Package the scenario with asset identities and resolved settings. Reuse useful manifest
   conventions and preserve the scientific inputs needed for reproducibility. Make CLI/API
   capabilities inspectable; evolve formats with maintained fixtures/readers and document changes.

**Acceptance:** one simple duct and one supported immersed-obstacle scenario run from both C# and
the data format without a Validation dependency. Round trips preserve resolved scientific inputs;
bad units, missing assets and unsupported combinations fail before device allocation or stepping.

### W2 — Local run, inspect and compare through the CLI

**Depends on:** W1. **Outcome:** a complete workflow that can be scripted or driven by an agent.

1. Add general validate, run, inspect and compare operations; keep numerical verification commands
   separately available. Choose final command names during implementation and test their help text.
2. Define local run identity, progress, cancellation, failure and result states. Emit a readable
   summary and machine-readable status with consistent exit codes and actual solver outcomes.
3. Add case bundles and parameter variations, with common assets reused and each resolved run saved.
   Compare runs on declared measurements and averaging windows, not only visual appearance.
4. Ship a documented local installation path, examples and a resource preflight that reports the
   selected device, estimated memory and supported features. Calibrate memory estimates against runs.

**Acceptance:** from a clean setup, a user runs an example, changes a parameter, compares two runs,
replays either run and cancels another cleanly. Required results survive viewer disconnection;
failed numerical runs cannot be reported as successful comparisons. These checks also form the
first executable examples for coding agents.

### W3 — Fan-enclosure airflow and pressure drop

**Depends on:** W1–W2. **Outcome:** the first useful engineering scenario and a simpler teaching variant.

1. Add geometry preparation for named stationary parts using primitives/SDF and imported meshes:
   explicit units, transforms, orientation, fluid-region selection and actionable geometry checks.
   Preserve names across edits so measurements and BC assignments remain reviewable. Start with
   supported files; native CAD editing and broad CAD-format conversion are separate extensions.
2. Add reusable aperture-weighted flow integration, mass balance and pressure sampling at named
   sections. Specify static versus total pressure, averaging and sign conventions. Convert the
   solver's kinematic pressure to pascals using the declared density; pressure differences must
   be gauge-independent. Begin with aligned sections before arbitrary surfaces.
3. Establish a prescribed-flow enclosure example and its pressure-loss measurement. Then evaluate
   a fan-curve/actuator representation for a fan-driven operating point. A curve relates pressure
   rise to flow; this is an established modeling option, e.g. [OpenFOAM fanPressure](https://doc.openfoam.com/2312/tools/processing/boundary-conditions/rtm/derived/inletOutlet/fanPressure/).
   Select and validate a compatible implementation rather than assuming the current patch system
   supports an internal pressure jump. Label prescribed flow, fan curves and resolved rotating
   blades as different models with different required inputs and validation.
4. Add a comparison example with two enclosure layouts: report flow, pressure drop, settling,
   grid/timestep sensitivity and runtime. Use an analytic/simple-duct check first, then an
   independent enclosure reference or measured data with frozen inputs and acceptance limits.
5. Assess the target flow regime and resolve the turbulence/wall-resolution strategy before making
   quantitative claims for a practical high-Reynolds-number fan enclosure. Keep a constrained,
   validated demonstration available while that assessment is open.

**Acceptance:** the supported example produces repeatable, independently checked flow/pressure
measurements and an understandable comparison. A general fan-driven enclosure claim additionally
requires the selected fan model and flow regime to pass their own checks. Existing rotating-fan
stability results cannot substitute for these accuracy checks.

The [prescribed-flow enclosure plan](https://github.com/hankbeasley/polycfd/blob/main/docs/plans/prescribed-flow-enclosure.md) defines the first
bounded comparison: a centered/offset stationary box, identical imposed flow, static pressure
measurements and a separately qualified reference. It reuses current scenario/study JSON;
the [work board](/docs/WORKBOARD) tracks implementation and acceptance separately from planning.

### W4 — Local browser workbench

**Depends on:** W1–W3. **Outcome:** the same airflow workflow is usable without writing code.

1. Add project creation, geometry import/inspection, named selections and forms backed by the
   scenario schema. Present guided defaults with access to advanced settings and units.
2. Add preflight, run/cancel/status, local run history and recovery of persisted run records when
   reconnecting. Restarting a computation from saved numerical state belongs to C1.
3. Provide live visualization with measurement plots, run comparison and exports.
   Build a fresh independent `src/workbench-ui` application; existing viewer UI and state
   are not dependencies. Keep `src/ui` available through the initial release and retire it
   later under W4-13a after explicit capability and replacement acceptance.
   Request slices/scalars at explicit cadences; preserve bounded frame and geometry lifetimes.
4. Add a guided fan-enclosure tutorial and an interactive student example. Verify that both can
   be completed from a clean install, including fixing an invalid setup and reopening results.

**Acceptance:** the browser creates a scenario, runs it, compares a variation and exports a bundle
that W2 runs with equivalent scientific settings. The local application works without a cloud
account. Browser closure does not silently discard an independently running job or required output.

The [workbench design exploration](https://github.com/hankbeasley/polycfd/blob/main/docs/w4-design/README.md) contains the feature/principle
brainstorm and a standalone mock prototype for engineers and learners. It is design
evidence, not completion of the runtime acceptance above. The proposed
[system architecture](https://github.com/hankbeasley/polycfd/blob/main/docs/w4-design/SYSTEM_DESIGN.md) and [phased implementation plan](https://github.com/hankbeasley/polycfd/blob/main/docs/plans/w4-workbench-implementation.md)
define the local job service, isolated worker and fresh React/Three.js frontend.
The existing runtime/viewer now supplies the versioned [HDF5](https://github.com/hankbeasley/polycfd/blob/main/docs/HDF5_FIELD_FORMAT.md) and
[PCFD product](https://github.com/hankbeasley/polycfd/blob/main/src/PolyCfd.Core/LiveViewer/BINARY_FORMAT.md) foundation, selective captures and scalar textures.
W4-05a–06c (contracts, local host, inputs, durable submission), W4-07a (runner seams) and W4-07b
(owned worker processes, scheduling, cancellation and force stop) are implemented, and W4-07c adds
terminal artifact verification, restart reconciliation and graceful shutdown (Gate A acceptance is recorded
on the work board). The W4-08 project, run and compare workflows of the new browser application run against the
real service, and the [Gate B browser journeys](https://github.com/hankbeasley/polycfd/blob/main/src/workbench-ui/README.md#browser-journeys-gate-b) exercise them on
CUDA (their acceptance is recorded on the work board); bounded fields and studies follow. W4-03 engineer/learner review remains
unperformed, and independent enclosure qualification remains a separate W3 gate.

## Next: heat transfer and buoyancy

### T1 — Temperature transport and prescribed thermal conditions

**Depends on:** W1–W3; expose through W4 as it ships.

1. Add an extensible transported-field contract and a temperature field with explicit locations,
   ownership, capture and serialization. Add density, heat capacity, conductivity/diffusivity and
   temperature-unit handling with consistent internal units.
2. Implement temperature advection/diffusion, prescribed temperature, heat flux, insulated walls,
   inlet/outlet treatment and volumetric heat sources. Define discretization and cut-cell heat
   accounting explicitly; the current nonconservative velocity remap is not automatically an
   acceptable thermal-energy transport scheme.
3. Add temperature probes, heat input/output and stored-energy diagnostics, plots and export.
   Verify diffusion, transport and source balance separately before combining them with flow.
4. Deliver a forced-flow heated duct and a room with prescribed supply-air temperature/flow and
   a return. This stage transports heat without temperature feeding back into momentum.

**Acceptance:** analytic/manufactured scalar cases converge under refinement; a transient heat
budget closes within a declared tolerance. The room example distinguishes imposed ventilation
from buoyant convection. Units, thermal BCs and outputs round-trip through CLI/browser scenarios.

### T2 — Cooling performance and air-side heat exchange

**Depends on:** T1 and W4.

1. Define the first condenser comparison around air-side flow distribution, pressure loss,
   heat rejection and outlet temperature. State the fan, ambient and coil-side conditions;
   define any effectiveness measure rather than displaying an undefined efficiency percentage.
2. Implement and validate a bounded first heat-exchanger representation, such as calibrated
   flow resistance plus a thermal source/heat-transfer law. An effectiveness-based model is one
   candidate; [OpenFOAM documents this approach](https://doc.openfoam.com/2212/tools/processing/numerics/fvoptions/sources/rtm/effectivenessHeatExchanger/).
   Track required correlation/measurement data and its valid range in the scenario.
3. Scope a separate extension for solid conduction and conjugate heat transfer when geometry-resolved
   fins, housings or temperature-dependent solid response are required. Preserve temperature/flux
   consistency at fluid/solid interfaces and verify a simple coupled benchmark first.
4. Deliver a cooling enclosure and simplified outdoor condenser comparison with heat budgets,
   reproducible inputs and grid/model sensitivity. Resolve insufficient fin/gap resolution through
   a validated reduced model or refinement, not geometric thickening alone.

**Acceptance:** heat transfer and pressure-loss results match a selected independent benchmark or
data set within predeclared limits. A simplified coil can ship before general conjugate heat
transfer, with its model clearly identified. Refrigerant phase change, compressor cycles, humidity,
radiation and complete AC-system efficiency are additional scoped physics, not implied by this release.

### T3 — Buoyancy and room thermal behavior

**Depends on:** T1 and T2's initial cooling workflow. General solid conduction is not a prerequisite
for room cases with prescribed thermal walls and heat sources.

1. Evaluate a Boussinesq model for the first supported temperature range: temperature affects the
   buoyancy force while the baseline flow remains incompressible. Define reference temperature,
   expansion coefficient, gravity and applicability checks. See the [OpenFOAM Boussinesq model](https://doc.openfoam.com/2212/tools/processing/models/thermophysical/equation-of-state/rtm/Boussinesq/).
2. Specify hydrostatic pressure treatment, boundary consistency and coupling order. Verify an
   equilibrium case and the zero-coupling limit before transient convection.
3. Validate natural and mixed convection with independent benchmark cases, checking velocity,
   temperature, heat transfer and grid/timestep sensitivity. Extend the flow-regime assessment
   from W3 to room jets and thermal mixing.
4. Deliver a room workflow with AC supply/return, a fan and heat loads; compare temperature at
   named locations, stratification and time response under declared operating conditions.

**Acceptance:** benchmark accuracy and heat/mass balances meet declared limits; disabling buoyancy
recovers the corresponding forced-flow thermal case. The room workflow exposes assumptions and
does not infer thermal comfort or equipment efficiency from temperature visualization alone.

## Supporting numerical development: scale up and improve geometry

### S1 — Single-GPU capacity and performance

**Starts with:** W2; continues on the agreed airflow/thermal workloads.

1. Establish device-memory and time-to-result budgets for small, typical and capacity-limited cases.
2. Profile pressure/coarse solves, geometry rebuilds and output independently. Optimize measured
   bottlenecks while preserving required fields, numerical checks and precision roles.
3. Reuse safe allocations and avoid unnecessary transfers; validate on a larger single GPU when
   available rather than inferring capacity/performance from nominal hardware specifications.

**Acceptance:** compare identical useful outputs and accuracy; demonstrate a measured improvement
or supported larger case with bounded memory. Follow the [performance acceptance rules](https://github.com/hankbeasley/polycfd/blob/main/docs/PERFORMANCE_VALIDATION.md#architecture-change-acceptance).

### S2 — Uniform multiblock on one GPU

**Depends on:** W1, S1 measurements and the AMR-02 [data-model alignment](/docs/amrex-alignment/DATA_MODEL_ALIGNMENT);
begin after the first local workflow unless blocked earlier. AMR-02 is a separate
behavior-preserving effort: explicit domain/box/field/level concepts with only one
supported level and patch. It adds no multiblock or refinement capability.
The [S2/S3 plan](/docs/amrex-alignment/S2_S3_PLAN) and [visual explainer](/)
describe the transition from that representation to coupled patches.

1. Define block identities, extents, physical coordinates, neighbor connectivity and field ownership.
2. Implement same-resolution halo exchange, BC separation and operators across block interfaces.
3. Extend pressure coupling, connected-component handling and reductions across blocks; verify
   monolithic versus partitioned domains, periodic seams and cut geometry crossing interfaces.
4. Extend scenario, capture, export and viewer contracts to blocks without changing user measurements.

**Acceptance:** partitioning a uniform problem changes neither its physical meaning nor its accepted
solution beyond declared tolerances. A one-block configuration remains supported with verified
numerical behavior and measured performance. No MPI or multi-GPU dependency is needed to deliver this milestone.

### S3 — Multiple spatial resolutions, then adaptive refinement

**Depends on:** S2; integrate each delivered thermal/motion capability explicitly.

The [implementation plan](/docs/amrex-alignment/S2_S3_PLAN#s3-fixed-refinement-then-adaptation)
proposes one full-domain coarse patch and one aligned 2:1 fine region as the first
bounded case. Keep the level-as-patch-collection model; a single coarse patch does
not eliminate fine-patch exchange or coarse/fine coupling. This initial subset does
not establish the full acceptance below.

1. Start with fixed refinement regions, a restricted refinement ratio and synchronized timesteps.
   Define valid nesting and reject unsupported layouts.
2. Validate coarse/fine transfers, face-flux consistency, composite pressure coupling/nullspaces
   and geometry representation. Specify conservation corrections appropriate to each discretization;
   copying the existing multigrid prolongation alone does not supply a multiresolution integrator.
3. Extend scalar/thermal interface treatment, heat budgets and measurement integration. Compare
   against uniform fine references for flow and heat, including immersed boundaries.
4. Add dynamic tagging/regridding as a later increment: transfer state, preserve applicable mass/heat
   budgets and rebuild geometry/connectivity safely. Validate moving geometry crossing levels
   separately. Time subcycling remains a later evidence-based decision.

**Acceptance:** fixed refinement first, then adaptation, reach declared measurement accuracy with
less memory or time than a comparable uniform fine grid. Report conservation and interface errors;
unsupported thermal/moving combinations remain unavailable until their checks pass.

### G1 — Complex assemblies and physically validated motion

**Depends on:** W3; overlaps numerical work only when a selected workflow needs it.

1. Extend named assemblies, transforms and motion laws with explicit supported combinations;
   validate disconnected pockets, intersecting geometry and topology changes.
2. Build moving immersed viscous-wall coefficients at the correct geometry/time and validate
   translated/rotating-wall cases, including momentum and energy transfer where applicable.
3. Add general surface force/torque extraction with consistent normals, area and reference frames;
   extend beyond the existing static analytic-cylinder diagnostic through manufactured benchmarks.
4. Establish a physically checked resolved rotating-fan enclosure case and compare its scope/cost
   with the W3 fan model. Couple moving thermal walls only after separate thermal verification.

**Acceptance:** motion, shear and forces have independent accuracy evidence. Longer finite/stable
runs supplement that evidence; they do not replace it. This milestone is required before claiming
general rotating-blade performance, not before shipping a validated prescribed-flow enclosure.

## Later: portable workers and agents

### C1 — Local GPU worker and recoverable execution

**Depends on:** W1–W4; cloud deployment remains later than complete local workflows.

1. Define a worker job protocol around existing scenario/run/result contracts with submit, status,
   cancel, resource capabilities and explicit ownership of outputs.
2. Package the worker in a GPU container and verify the selected Linux/NVIDIA runtime and intended
   local platform, including Windows/WSL where supported. Retain the native execution path.
3. Add numerical checkpoint/restart with versioned state, geometry/motion time, solver requirements
   and output position. Compare resumed and uninterrupted runs; configuration replay alone is insufficient.
4. Let the local browser use a locally served endpoint with predictable lifecycle and connection errors.

**Acceptance:** native and container runs agree within the documented numerical tolerance; jobs
survive browser reconnection, and validated checkpoints resume after worker interruption.

### C2 — On-demand remote GPU and optional orchestration

**Depends on:** C1.

1. Run the same worker image on one rented GPU machine, with explicit device compatibility, job
   limits, cancellation, cleanup and durable result locations. Prove this before fleet management.
2. Add an optional orchestrator with authenticated workers, assignment, heartbeats and recovery.
   A personal GPU worker can register through an outbound connection; do not require public
   inbound access to a user's computer.
3. Separate job/control messages from result transfer. Cache assets by identity, keep working
   fields near the worker, request bounded scalar/slice previews and persist selected artifacts.
4. Begin remote browser access through the service/relay; measure bandwidth and latency before
   adding direct browser-to-worker routing. Define offline/disconnected behavior and data ownership.

**Acceptance:** the same scenario runs locally and remotely, produces traceable equivalent results,
and recovers from disconnects without duplicate jobs or unbounded output. Local standalone use
still requires no orchestrator. Distributed single-simulation execution and fleet throughput are
future decisions rather than requirements of the initial scale-up plan.

### A1 — Modeling-tool and agent scenario workflow

**Depends on:** W1–W4; can run entirely locally. Agent-friendly schemas/help/errors start in W1.

1. Publish capability/schema discovery, executable API examples, machine-readable preflight and
   result summaries. A coding agent should be able to find supported operations without reading
   solver internals; human documentation and agent examples use the same public contracts.
2. Define a modeling-tool adapter that supplies geometry, units, named regions, transforms,
   parameters and provenance. Validate geometry and resolve region assignments after model edits.
   Initial interchange can use supported meshes/parametric primitives; choose CAD adapters later.
3. Add a request-to-scenario workflow: identify missing physical inputs, produce a reviewable
   scenario, validate it, run a bounded example and summarize results with links to actual artifacts.

**Acceptance:** repeatable tasks include an enclosure variation and a student flow example, then
thermal examples as T1–T3 ship. Invalid geometry, ambiguous units, lost selections and unsupported
physics produce actionable outcomes. A plausible-looking 3D model is not sufficient acceptance.

### A2 — Agent experiments and code contributions

**Depends on:** A1 and the validated physics needed by each experiment.

1. Support measured parameter studies and result comparisons within declared compute/time limits,
   with saved inputs, assumptions and reproducible outputs for every candidate.
2. Define evaluations for successful setup, meaningful diagnostics, recovery from errors and correct
   interpretation of supported results. Evaluate across agent/model updates without binding the
   scientific format to a single provider.
3. Provide a separate contributor workflow for agents implementing extensions: small examples,
   clear module contracts, targeted verification and required numerical/performance acceptance.
   Generating an extension is distinct from establishing that its physics is supported.

**Acceptance:** an agent can complete a supported investigation and another user can reproduce it.
New physics/code reaches users only after the same review and validation as other contributions.

## How to execute the roadmap

Use the [work board](/docs/WORKBOARD) for status, owners, blockers, evidence and next actions.
[Active plans](https://github.com/hankbeasley/polycfd/blob/main/docs/plans/README.md) define detailed tasks and dependencies. The implemented initial
scenario profile is described by the [format and API guide](https://github.com/hankbeasley/polycfd/blob/main/docs/SCENARIO_FORMAT.md).
Update the board in the same change as implementation; avoid duplicate task status in this document.

Each numbered increment above should be split into independently reviewable changes when necessary.
Before starting one, record its concrete example, dependencies, public/API effect and acceptance
checks in its active plan and link the board row to that task. Do not assign calendar estimates until scope,
available development capacity, hardware and reference data are known.

A milestone is delivered when the complete supported workflow works, its numerical claims have
evidence, affected workflow/performance checks pass and current user documentation is updated.
Preserve the established [regression coverage](https://github.com/hankbeasley/polycfd/blob/main/validation/PolyCfd.Validation/README.md) and
[runtime ownership rules](https://github.com/hankbeasley/polycfd/blob/main/docs/RUNTIME_CONTRACTS.md). Distinguish correctness, physical accuracy,
reproducibility, usability and performance; none alone establishes the others.

### Next workflow increments

Parameter variations and matching-window comparisons now use shared JSON scenario execution;
see the [delivered workflow](https://github.com/hankbeasley/polycfd/blob/main/docs/PARAMETER_STUDIES.md). Next priorities are:

1. Recover the outstanding CPU numerical-regression coverage and calibrate W2 resource preflight when suitable instrumentation is available; estimates remain explicitly uncalibrated until then.
2. Add enclosure geometry and independent enclosure/fan accuracy evidence.
3. Expose the same sequence through W4's browser.

### Decisions to resolve at their milestones

| Decision | Resolve by | Evidence needed |
| --- | --- | --- |
| First enclosure geometry, fan representation and reference data | W3 | Target operating range, available curves/measurements, validation cost and resolution |
| Turbulence and wall treatment for practical enclosure/room cases | W3, extend in T3 | Reynolds numbers, mesh feasibility, accuracy targets and independent references |
| First condenser model: prescribed coil conditions, calibrated exchanger or resolved solids | T2 | Requested output, available thermal/pressure-loss data and resolvable geometry |
| Refinement ratios, conservation strategy and pressure coupling | S2–S3 | Uniform-versus-partitioned and uniform-fine comparisons on one GPU |
| First GPU/container platform and cloud provider | C1–C2 | Driver/runtime compatibility, reproducible deployment and measured cost per useful run |
| Modeling adapters and agent interfaces/providers | A1–A2 | Model interchange quality, stable selections and repeatable end-to-end task success |

No unresolved item in this table blocks starting W1. Public API names, fan/thermal model selection,
cloud transport and agent tooling remain implementation decisions with explicit evaluation points.