# PolyCFD roadmap **Direction agreed with the project owner; current implementation reviewed 2026-09-19; AMReX alignment and transport planning updated 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 | | Better transport on existing grids | Reduce demonstrated transport error on selected current cases with explicit momentum budgets and measured cost to reach target accuracy | TRN-01; improvements require comparative validation | | 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. For the refinement foundation, sequence AMR-02 data alignment, TRN-01 single-grid transport validation, S2 interface validation, then S3. S2 layout work can overlap transport development. This numerical sequence does not displace the local workflow priorities above; coordinate its scalar work with T1. ## 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. Coordinate flux infrastructure and scalar-budget tests with [TRN-01](/docs/amrex-alignment/SINGLE_LEVEL_TRANSPORT). Its scalar test harness does not deliver T1, and T1 scalar work need not wait for all momentum qualification. 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: transport, scale and geometry ### TRN-01 — Conservative transport and single-grid accuracy **Integration depends on:** accepted AMR-02 data alignment. Current-method diagnostics and bounded experiments may start earlier. Establish the transport method and flux contract before finalizing S2 advection interfaces; accept its supported single-level scope before S2/S3 transport acceptance. See the [transport plan](/docs/amrex-alignment/SINGLE_LEVEL_TRANSPORT). 1. Measure current momentum budgets by stage, including pressure, viscosity, forces, boundaries and motion; assess kinetic-energy evolution separately. 2. Validate a conservative scalar building block, then formulate momentum transport for the staggered MAC control volumes and its pressure/time coupling. Start with a limited second-order finite-volume candidate; exact method selection requires evidence. 3. Qualify physical boundaries, stationary cut cells and small-cell stability; validate moving geometry separately. Preserve existing supported cases during the migration. 4. Demonstrate single-grid benefit on preselected transport-sensitive cases, comparing accuracy at matched grid/timestep and measured cost to reach a target accuracy. **Acceptance:** conservation, stability and existing scientific checks pass for the declared scope, with demonstrated accuracy benefit on the selected current workloads and cost within agreed limits. Conservation alone does not prove lower error. Retain known qualification gaps; do not weaken reference protocols or performance allowances. No improvement to splitting, diffusion or cut-boundary accuracy follows automatically. This is a numerical change, outside the behavior-preserving AMR-02 effort. ### 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. Layout/ownership work can overlap TRN-01, but the accepted transport method and flux contract must guide advection interfaces. Full S2 transport acceptance requires TRN-01's validated single-level scope and equivalent partitioned results. 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, including consistent shared transport fluxes and the accepted method's stencil/stage requirements. 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 and TRN-01 transport acceptance for the intended cases; integrate each delivered thermal/motion capability explicitly. S3 adds coarse/fine flux synchronization and composite equations to an already validated single-level method. 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 | | Conservative MAC transport, temporal coupling, limiter and cut-cell stability | TRN-01, before finalizing S2 transport interfaces | Single-grid budgets and accuracy, existing regression cases, timestep limits and cost to target accuracy | | 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.